idnits 2.17.1 draft-wilde-service-link-rel-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (April 22, 2015) is 3290 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (ref. '2') (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft UC Berkeley 4 Intended status: Informational April 22, 2015 5 Expires: October 24, 2015 7 Link Relation Types for Web Services 8 draft-wilde-service-link-rel-00 10 Abstract 12 Many resources provided on the Web are part of a sets of resources 13 that are provided in a context that is defined and managed by one 14 particular service provider. Often, these sets of resources are 15 referred to as "Web Services" or "Web APIs". This specification 16 defines two link relations that allow to represent relationships from 17 those resources to ones that provide documentation or descriptions of 18 the Web services. The difference between these concepts is that 19 documentation is primarily intended for human consumers, whereas 20 descriptions are primarily intended for automated consumers. 22 Note to Readers 24 Please discuss this draft on the apps-discuss mailing list [1]. 26 Online access to all versions and files is available on github [2]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on October 24, 2015. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Web Services . . . . . . . . . . . . . . . . . . . . . . . . 3 65 3.1. Documenting Web Services . . . . . . . . . . . . . . . . 4 66 3.2. Describing Web Services . . . . . . . . . . . . . . . . . 4 67 4. Link Relations for Web Services . . . . . . . . . . . . . . . 4 68 4.1. The service-doc Link Relation Type . . . . . . . . . . . 5 69 4.2. The service-desc Link Relation Type . . . . . . . . . . . 5 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 71 5.1. Link Relation Type: service-doc . . . . . . . . . . . . . 5 72 5.2. Link Relation Type: service-desc . . . . . . . . . . . . 5 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 74 7. Normative References . . . . . . . . . . . . . . . . . . . . 5 75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 6 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 78 1. Introduction 80 One of the defining aspects of the Web is that it is possible to 81 interact with Web resources without any prior knowledge of the 82 specifics of the resource. By using URIs, HTTP, and media types, the 83 Web's uniform interface allows interactions with resources without 84 the more complex binding procedures of other approaches. 86 However, many resources on the Web are provided as part of a set of 87 resources that are referred to as a "Web Service" or a "Web API". In 88 many cases, these services or APIs are defined and managed as a 89 whole, and it may be desirable for clients to be able to discover 90 this service definition information. 92 Service definition can be separated into two broad categories: One 93 category is targeted for human users and often uses generic formats 94 or human readable documents, such as HTML or PDF. The other category 95 is structured information that followed some more formalized 96 description model, and is intended for consumption by machines, for 97 example for tools and code libraries. 99 In the context of this specification, the human-oriented variant is 100 referred to as "documentation", and the machine-oriented variant is 101 referred to as "description". 103 These two categories are not always mutually exclusive, as there are 104 formats that have been proposed that are intended for both human 105 consumption, and for interpretation by machine clients. 107 This specification places no constraints on the specific formats used 108 for either of those two categories. It simply allows publishers of a 109 Web service to make the documentation and/or the description of their 110 service discoverable, and defines two link relations that serve that 111 purpose. 113 2. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in RFC 2119 [1]. 119 3. Web Services 121 "Web Services" or "Web APIs" (sometimes also referred to as "HTTP 122 API" or "REST API") are a way to expose information and services on 123 the Web. Following the principles of Web architecture, they expose 124 URI-identified resources, which are then accessed and transferred 125 using a specific representation. Many services use representations 126 that contain links, and often these links are typed links. 128 Using typed links, resources can identify relationships to other 129 resources. RFC 5988 [2] establishes a framework of well-known 130 registered link relation types, which are identified by simple 131 strings and registered in an IANA registry. Any resource that 132 supports typed links according to RFC 5988 can then use this 133 identifier to represent resource relationships on the Web without 134 having to re-invent the registered relation type. 136 In recent years, Web services and documentation and description 137 languages have gained popularity, due to the general popularity of 138 the Web as a platform for providing information and services. 139 However, the exact design documentation and description languages 140 varies with a number of factors, such as the general application 141 domain, the preferred application data model, and the preferred 142 approach for exposing services. 144 It makes sense to provide service providers with a unified way to 145 link to service documentation and/or description. This link should 146 not make any assumptions about the provided type of documentation 147 and/or description, so that service providers can choose the ones 148 that best fit their services and needs. 150 3.1. Documenting Web Services 152 In the context of this specification, "documentation" refers to 153 information that is intended for human consumption. Typical formats 154 for this kind of documentation are HTML and PDF. 156 Documentation is often structured, but the exact kind of structure 157 depends on the structure of the service that is documented, as well 158 as on the specific way in which the documentation authors choose to 159 document it. 161 3.2. Describing Web Services 163 In the context of this specification, "description" refers to 164 information that is intended for machine consumption. Typical 165 formats for this are dictated by the technology underlying the 166 service itself, which means that in today's format landscape, 167 description formats exist in XML, JSON, RDF, and a variety of other 168 languages. 170 Descriptions are always structured, but the structuring principles 171 depend on the nature of the described service. For example, one of 172 the earlier service description approaches, the Web Services 173 Description Language (WSDL), uses "operations" as its core concept, 174 which are essentially identical to function calls, because the 175 underlying model is based on that of Remote Procedure Calls (RPC). 176 Other description languages for non-RPC approaches to services will 177 use different structuring approaches. 179 4. Link Relations for Web Services 181 In order to allow Web services to represent the relation of 182 individual resources to service documentation or description, this 183 specification introduces and registers two new link relation types. 185 4.1. The service-doc Link Relation Type 187 The service-doc link relation type is used to represent the fact that 188 a resource is part of a bigger set of resources that are documented 189 at a specific URI. The target resource is expected to provide 190 documentation that is intended for human consumption. 192 4.2. The service-desc Link Relation Type 194 The service-desc link relation type is used to represent the fact 195 that a resource is part of a bigger set of resources that are 196 described at a specific URI. The target resource is expected to 197 provide a service description that is intended for machine 198 consumption. Very often, it is provided in a format that is consumed 199 by tools, code libraries, or similar components. 201 5. IANA Considerations 203 The link relation types below have been registered by IANA per 204 Section 6.2.1 of RFC 5988 [2]: 206 5.1. Link Relation Type: service-doc 208 Relation Name: service-doc 210 Description: Linking to service documentation that is primarily 211 intended for human consumption. 213 Reference: [[ This document ]] 215 5.2. Link Relation Type: service-desc 217 Relation Name: service-desc 219 Description: Linking to service description that is primarily 220 intended for consumption by machines. 222 Reference: [[ This document ]] 224 6. Security Considerations 226 ... 228 7. Normative References 230 [1] Bradner, S., "Key words for use in RFCs to Indicate 231 Requirement Levels", RFC 2119, March 1997. 233 [2] Nottingham, M., "Web Linking", RFC 5988, October 2010. 235 Appendix A. Acknowledgements 237 Thanks for comments and suggestions provided by Mike Amundsen and 238 Darrell Miller 240 Author's Address 242 Erik Wilde 243 UC Berkeley 245 Email: dret@berkeley.edu 246 URI: http://dret.net/netdret/