Link Relation Types for Web Services
draft-wilde-service-link-rel-00

Network Working Group                                           E. Wilde
Internet-Draft                                               UC Berkeley
Intended status: Informational                            April 22, 2015
Expires: October 24, 2015

                  Link Relation Types for Web Services
                    draft-wilde-service-link-rel-00

Abstract

   Many resources provided on the Web are part of a sets of resources
   that are provided in a context that is defined and managed by one
   particular service provider.  Often, these sets of resources are
   referred to as "Web Services" or "Web APIs".  This specification
   defines two link relations that allow to represent relationships from
   those resources to ones that provide documentation or descriptions of
   the Web services.  The difference between these concepts is that
   documentation is primarily intended for human consumers, whereas
   descriptions are primarily intended for automated consumers.

Note to Readers

   Please discuss this draft on the apps-discuss mailing list [1].

   Online access to all versions and files is available on github [2].

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on October 24, 2015.

Wilde                   Expires October 24, 2015                [Page 1]
Internet-Draft      Web Services Link Relation Types          April 2015

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Web Services  . . . . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Documenting Web Services  . . . . . . . . . . . . . . . .   4
     3.2.  Describing Web Services . . . . . . . . . . . . . . . . .   4
   4.  Link Relations for Web Services . . . . . . . . . . . . . . .   4
     4.1.  The service-doc Link Relation Type  . . . . . . . . . . .   5
     4.2.  The service-desc Link Relation Type . . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
     5.1.  Link Relation Type: service-doc . . . . . . . . . . . . .   5
     5.2.  Link Relation Type: service-desc  . . . . . . . . . . . .   5
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .   5
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   One of the defining aspects of the Web is that it is possible to
   interact with Web resources without any prior knowledge of the
   specifics of the resource.  By using URIs, HTTP, and media types, the
   Web's uniform interface allows interactions with resources without
   the more complex binding procedures of other approaches.

   However, many resources on the Web are provided as part of a set of
   resources that are referred to as a "Web Service" or a "Web API".  In
   many cases, these services or APIs are defined and managed as a
   whole, and it may be desirable for clients to be able to discover
   this service definition information.

Wilde                   Expires October 24, 2015                [Page 2]
Internet-Draft      Web Services Link Relation Types          April 2015

   Service definition can be separated into two broad categories: One
   category is targeted for human users and often uses generic formats
   or human readable documents, such as HTML or PDF.  The other category
   is structured information that followed some more formalized
   description model, and is intended for consumption by machines, for
   example for tools and code libraries.

   In the context of this specification, the human-oriented variant is
   referred to as "documentation", and the machine-oriented variant is
   referred to as "description".

   These two categories are not always mutually exclusive, as there are
   formats that have been proposed that are intended for both human
   consumption, and for interpretation by machine clients.

   This specification places no constraints on the specific formats used
   for either of those two categories.  It simply allows publishers of a
   Web service to make the documentation and/or the description of their
   service discoverable, and defines two link relations that serve that
   purpose.

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [1].

3.  Web Services

   "Web Services" or "Web APIs" (sometimes also referred to as "HTTP
   API" or "REST API") are a way to expose information and services on
   the Web. Following the principles of Web architecture, they expose
   URI-identified resources, which are then accessed and transferred
   using a specific representation.  Many services use representations
   that contain links, and often these links are typed links.

   Using typed links, resources can identify relationships to other
   resources.  RFC 5988 [2] establishes a framework of well-known
   registered link relation types, which are identified by simple
   strings and registered in an IANA registry.  Any resource that
   supports typed links according to RFC 5988 can then use this
   identifier to represent resource relationships on the Web without
   having to re-invent the registered relation type.

   In recent years, Web services and documentation and description
   languages have gained popularity, due to the general popularity of
   the Web as a platform for providing information and services.
   However, the exact design documentation and description languages

Wilde                   Expires October 24, 2015                [Page 3]
Internet-Draft      Web Services Link Relation Types          April 2015

   varies with a number of factors, such as the general application
   domain, the preferred application data model, and the preferred
   approach for exposing services.

   It makes sense to provide service providers with a unified way to
   link to service documentation and/or description.  This link should
   not make any assumptions about the provided type of documentation
   and/or description, so that service providers can choose the ones
   that best fit their services and needs.

3.1.  Documenting Web Services

   In the context of this specification, "documentation" refers to
   information that is intended for human consumption.  Typical formats
   for this kind of documentation are HTML and PDF.

   Documentation is often structured, but the exact kind of structure
   depends on the structure of the service that is documented, as well
   as on the specific way in which the documentation authors choose to
   document it.

3.2.  Describing Web Services

   In the context of this specification, "description" refers to
   information that is intended for machine consumption.  Typical
   formats for this are dictated by the technology underlying the
   service itself, which means that in today's format landscape,
   description formats exist in XML, JSON, RDF, and a variety of other
   languages.

   Descriptions are always structured, but the structuring principles
   depend on the nature of the described service.  For example, one of
   the earlier service description approaches, the Web Services
   Description Language (WSDL), uses "operations" as its core concept,
   which are essentially identical to function calls, because the
   underlying model is based on that of Remote Procedure Calls (RPC).
   Other description languages for non-RPC approaches to services will
   use different structuring approaches.

4.  Link Relations for Web Services

   In order to allow Web services to represent the relation of
   individual resources to service documentation or description, this
   specification introduces and registers two new link relation types.

Wilde                   Expires October 24, 2015                [Page 4]
Internet-Draft      Web Services Link Relation Types          April 2015

4.1.  The service-doc Link Relation Type

   The service-doc link relation type is used to represent the fact that
   a resource is part of a bigger set of resources that are documented
   at a specific URI.  The target resource is expected to provide
   documentation that is intended for human consumption.

4.2.  The service-desc Link Relation Type

   The service-desc link relation type is used to represent the fact
   that a resource is part of a bigger set of resources that are
   described at a specific URI.  The target resource is expected to
   provide a service description that is intended for machine
   consumption.  Very often, it is provided in a format that is consumed
   by tools, code libraries, or similar components.

5.  IANA Considerations

   The link relation types below have been registered by IANA per
   Section 6.2.1 of RFC 5988 [2]:

5.1.  Link Relation Type: service-doc

      Relation Name: service-doc

      Description: Linking to service documentation that is primarily
      intended for human consumption.

      Reference: [[ This document ]]

5.2.  Link Relation Type: service-desc

      Relation Name: service-desc

      Description: Linking to service description that is primarily
      intended for consumption by machines.

      Reference: [[ This document ]]

6.  Security Considerations

   ...

7.  Normative References

   [1]        Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", RFC 2119, March 1997.

Wilde                   Expires October 24, 2015                [Page 5]
Internet-Draft      Web Services Link Relation Types          April 2015

   [2]        Nottingham, M., "Web Linking", RFC 5988, October 2010.

Appendix A.  Acknowledgements

   Thanks for comments and suggestions provided by Mike Amundsen and
   Darrell Miller

Author's Address

   Erik Wilde
   UC Berkeley

   Email: dret@berkeley.edu
   URI:   http://dret.net/netdret/

Wilde                   Expires October 24, 2015                [Page 6]