idnits 2.17.1 draft-wilde-service-link-rel-03.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 : ---------------------------------------------------------------------------- No issues found here. 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 (March 13, 2017) is 2594 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-06) exists of draft-nottingham-json-home-04 Summary: 1 error (**), 0 flaws (~~), 3 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 CA Technologies 4 Intended status: Informational March 13, 2017 5 Expires: September 14, 2017 7 Link Relation Types for Web Services 8 draft-wilde-service-link-rel-03 10 Abstract 12 Many resources provided on the Web are part of sets of resources that 13 are provided in a context that is managed by one particular service 14 provider. Often, these sets of resources are referred to as "Web 15 Services" or "Web APIs". This specification defines link relations 16 for representing relationships from those resources to ones that 17 provide documentation or descriptions of the Web services. The 18 difference between these concepts is that documentation is primarily 19 intended for human consumers, whereas descriptions are primarily 20 intended for automated consumers. It also defines a link relation to 21 identify a status resource that is used to represent operational 22 information about a service's status. 24 Note to Readers 26 Please discuss this draft on the ART mailing list 27 (). 29 Online access to all versions and files is available on GitHub 30 (). 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on September 14, 2017. 49 Copyright Notice 51 Copyright (c) 2017 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3. Web Services . . . . . . . . . . . . . . . . . . . . . . . . 4 69 3.1. Documenting Web Services . . . . . . . . . . . . . . . . 4 70 3.2. Describing Web Services . . . . . . . . . . . . . . . . . 5 71 3.3. Unified Documentation/Description . . . . . . . . . . . . 5 72 4. Link Relations for Web Services . . . . . . . . . . . . . . . 5 73 4.1. The service-doc Link Relation Type . . . . . . . . . . . 5 74 4.2. The service-desc Link Relation Type . . . . . . . . . . . 6 75 5. Web Service Status Resources . . . . . . . . . . . . . . . . 6 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 77 6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 6 78 6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7 79 6.3. Link Relation Type: status . . . . . . . . . . . . . . . 7 80 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 81 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 82 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 83 8.2. Informative References . . . . . . . . . . . . . . . . . 7 84 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 87 1. Introduction 89 One of the defining aspects of the Web is that it is possible to 90 interact with Web resources without any prior knowledge of the 91 specifics of the resource. Following Web Architecture 92 [W3C.REC-webarch-20041215] by using URIs, HTTP, and media types, the 93 Web's uniform interface allows interactions with resources without 94 the more complex binding procedures of other approaches. 96 Many resources on the Web are provided as part of a set of resources 97 that are referred to as a "Web Service" or a "Web API". In many 98 cases, these services or APIs are defined and managed as a whole, and 99 it may be desirable for clients to be able to discover this service 100 information. 102 Service information can be broadly separated into two categories: One 103 category is primarily targeted for human users and often uses generic 104 representations for human readable documents, such as HTML or PDF. 105 The other category is structured information that follows some more 106 formalized description model, and is primarily intended for 107 consumption by machines, for example for tools and code libraries. 109 In the context of this memo, the human-oriented variant is referred 110 to as "documentation", and the machine-oriented variant is referred 111 to as "description". 113 These two categories are not necessarily mutually exclusive, as there 114 are representations that have been proposed that are intended for 115 both human consumption, and for interpretation by machine clients. 116 In addition, a typical pattern for service documentation/description 117 is that there is human-oriented high-level documentation that is 118 intended to put a service in context and explain the general model, 119 which is complemented by a machine-level description that is intended 120 as a detailed technical description of the service. These two 121 resources could be interlinked, but since they are intended for 122 different audiences, it can make sense to provide entry points for 123 both of them. 125 This memo places no constraints on the specific representations used 126 for either of those two categories. It simply allows providers of a 127 Web service to make the documentation and/or the description of their 128 services discoverable, and defines two link relations that serve that 129 purpose. 131 In addition, this memo defines a link relation that allows providers 132 of a Web service to link to a resource that represents status 133 information about the service. This information often represents 134 operational information that allows service consumers to retrieve 135 information about "service health" and related issues. 137 2. Terminology 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 141 document are to be interpreted as described in RFC 2119 [RFC2119]. 143 3. Web Services 145 "Web Services" or "Web APIs" (sometimes also referred to as "HTTP 146 API" or "REST API") are a way to expose information and services on 147 the Web. Following the principles of Web architecture 148 [W3C.REC-webarch-20041215], they expose URI-identified resources, 149 which are then accessed and transferred using a specific 150 representation. Many services use representations that contain 151 links, and often these links are typed links. 153 Using typed links, resources can identify relationship types to other 154 resources. RFC 5988 [RFC5988] establishes a framework of registered 155 link relation types, which are identified by simple strings and 156 registered in an IANA registry. Any resource that supports typed 157 links according to RFC 5988 can then use these identifiers to 158 represent resource relationships on the Web without having to re- 159 invent registered relation types. 161 In recent years, Web services as well as their documentation and 162 description languages have gained popularity, due to the general 163 popularity of the Web as a platform for providing information and 164 services. However, the design of documentation and description 165 languages varies with a number of factors, such as the general 166 application domain, the preferred application data model, and the 167 preferred approach for exposing services. 169 This specification allows service providers to use a unified way to 170 link to service documentation and/or description. This link should 171 not make any assumptions about the provided type of documentation 172 and/or description, so that service providers can choose the ones 173 that best fit their services and needs. 175 3.1. Documenting Web Services 177 In the context of this specification, "documentation" refers to 178 information that is primarily intended for human consumption. 179 Typical representations for this kind of documentation are HTML and 180 PDF. 182 Documentation is often structured, but the exact kind of structure 183 depends on the structure of the service that is documented, as well 184 as on the specific way in which the documentation authors choose to 185 document it. 187 3.2. Describing Web Services 189 In the context of this specification, "description" refers to 190 information that is primarily intended for machine consumption. 191 Typical representations for this are dictated by the technology 192 underlying the service itself, which means that in today's technology 193 landscape, description formats exist that are based on XML, JSON, 194 RDF, and a variety of other structured data models. Also, in each of 195 those technologies, there may be a variety of languages that are 196 defined to achieve the same general purpose of describing a Web 197 service. 199 Descriptions are always structured, but the structuring principles 200 depend on the nature of the described service. For example, one of 201 the earlier service description approaches, the Web Services 202 Description Language (WSDL), uses "operations" as its core concept, 203 which are essentially identical to function calls, because the 204 underlying model is based on that of the Remote Procedure Call (RPC) 205 model. Other description languages for non-RPC approaches to 206 services will use different structuring approaches. 208 3.3. Unified Documentation/Description 210 If service providers use an approach where there is no distinction of 211 service documentation Section 3.1 and service description 212 Section 3.2, then they may not feel the need to use two separate 213 links. In such a case, an alternative approach is to use the 214 "service" link relation type, which has no indication of whether it 215 links to documentation or description, and thus may be better fit if 216 no such differentiation is required. 218 4. Link Relations for Web Services 220 In order to allow Web services to represent the relation of 221 individual resources to service documentation or description, this 222 specification introduces and registers two new link relation types. 224 4.1. The service-doc Link Relation Type 226 The "service-doc" link relation type is used to represent the fact 227 that a resource is part of a bigger set of resources that are 228 documented at a specific URI. The target resource is expected to 229 provide documentation that is primarily intended for human 230 consumption. 232 4.2. The service-desc Link Relation Type 234 The "service-desc" link relation type is used to represent the fact 235 that a resource is part of a bigger set of resources that are 236 described at a specific URI. The target resource is expected to 237 provide a service description that is primarily intended for machine 238 consumption. In many cases, it is provided in a representation that 239 is consumed by tools, code libraries, or similar components. 241 5. Web Service Status Resources 243 Web services providing access to a set of resources often are hosted 244 and operated in an environment for which status information may be 245 available. This information may be as simple as confirming that a 246 service is operational, or may provide additional information about 247 different aspects of a service, and/or a history of status 248 information, possibly listing incidents and their resolution. 250 The "status" link relation type can be used to link to such a status 251 resource, allowing service consumers to retrieve status information 252 about a Web service's status. Such a link may not be available from 253 all resources provided by a Web service, but from key resources such 254 as a Web service's home resource [I-D.nottingham-json-home]. 256 This memo does not restrict the representation of a status resource 257 in any way. It may be primarily focused on human or machine 258 consumption, or a combination of both. It may be a simple "traffic 259 light" indicator for service health, or a more sophisticated 260 representation conveying more detailed information such as service 261 subsystems and/or a status history. 263 6. IANA Considerations 265 The link relation types below have been registered by IANA per 266 Section 6.2.1 of RFC 5988 [RFC5988]: 268 6.1. Link Relation Type: service-doc 270 Relation Name: service-doc 272 Description: Linking to service documentation that is primarily 273 intended for human consumption. 275 Reference: [[ This document ]] 277 6.2. Link Relation Type: service-desc 279 Relation Name: service-desc 281 Description: Linking to service description that is primarily 282 intended for consumption by machines. 284 Reference: [[ This document ]] 286 6.3. Link Relation Type: status 288 Relation Name: status 290 Description: Linking to a resource that represents the status of a 291 Web service or API. 293 Reference: [[ This document ]] 295 7. Security Considerations 297 ... 299 8. References 301 8.1. Normative References 303 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 304 Requirement Levels", RFC 2119, March 1997. 306 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 308 8.2. Informative References 310 [I-D.nottingham-json-home] 311 Nottingham, M., "Home Documents for HTTP APIs", draft- 312 nottingham-json-home-04 (work in progress), May 2016. 314 [W3C.REC-webarch-20041215] 315 Jacobs, I. and N. Walsh, "Architecture of the World Wide 316 Web, Volume One", World Wide Web Consortium 317 Recommendation REC-webarch-20041215, December 2004, 318 . 320 Appendix A. Acknowledgements 322 Thanks for comments and suggestions provided by Mike Amundsen, Oliver 323 Gierke, Sebastien Lambla, and Darrell Miller. 325 Author's Address 327 Erik Wilde 328 CA Technologies 330 Email: erik.wilde@dret.net 331 URI: http://dret.net/netdret/