idnits 2.17.1 draft-wilde-service-link-rel-06.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 (August 1, 2018) is 2094 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-nottingham-json-home-04 Summary: 0 errors (**), 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 August 1, 2018 5 Expires: February 2, 2019 7 Link Relation Types for Web Services 8 draft-wilde-service-link-rel-06 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, descriptions, or metadata for these Web 18 services. Documentation is primarily intended for human consumers, 19 whereas descriptions are primarily intended for automated consumers; 20 metadata is supposed to be information about a service's context. It 21 also defines a link relation to identify status resources that are 22 used to represent operational information about service 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 https://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 February 2, 2019. 49 Copyright Notice 51 Copyright (c) 2018 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 (https://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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3. Web Services . . . . . . . . . . . . . . . . . . . . . . . . 4 69 3.1. Documenting Web Services . . . . . . . . . . . . . . . . 5 70 3.2. Describing Web Services . . . . . . . . . . . . . . . . . 5 71 3.3. Unified Documentation/Description . . . . . . . . . . . . 5 72 4. Link Relations for Web Services . . . . . . . . . . . . . . . 6 73 4.1. The service-doc Link Relation Type . . . . . . . . . . . 6 74 4.2. The service-desc Link Relation Type . . . . . . . . . . . 6 75 4.3. The service-meta Link Relation Type . . . . . . . . . . . 6 76 5. Web Service Status Resources . . . . . . . . . . . . . . . . 7 77 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 78 6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 7 79 6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7 80 6.3. Link Relation Type: service-meta . . . . . . . . . . . . 8 81 6.4. Link Relation Type: status . . . . . . . . . . . . . . . 8 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 83 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 84 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 85 8.2. Informative References . . . . . . . . . . . . . . . . . 8 86 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 89 1. Introduction 91 One of the defining aspects of the Web is that it is possible to 92 interact with Web resources without any prior knowledge of the 93 specifics of the resource. Following Web Architecture 94 [W3C.REC-webarch-20041215] by using URIs, HTTP, and media types, the 95 Web's uniform interface allows interactions with resources without 96 the more complex binding procedures often necessary with other 97 approaches. 99 Many resources on the Web are provided as part of a set of resources 100 that are referred to as a "Web Service" or a "Web API". In many 101 cases, these services or APIs are defined and managed as a whole, and 102 it may be desirable for clients to be able to discover this service 103 information. 105 Service information that provides information on how to use service 106 resources can be broadly separated into two categories: One category 107 is primarily targeted for human users and often uses generic 108 representations for human readable documents, such as HTML or PDF. 109 The other category is structured information that follows some more 110 formalized description model, and is primarily intended for 111 consumption by machines, for example for tools and code libraries. 113 In the context of this memo, the human-oriented variant is referred 114 to as "documentation", and the machine-oriented variant is referred 115 to as "description". 117 These two categories are not necessarily mutually exclusive, as there 118 are representations that have been proposed that are intended for 119 both human consumption, and for interpretation by machine clients. 120 In addition, a typical pattern for service documentation/description 121 is that there is human-oriented high-level documentation that is 122 intended to put a service in context and explain the general model, 123 which is complemented by a machine-level description that is intended 124 as a detailed technical description of the service. These two 125 resources could be interlinked, but since they are intended for 126 different audiences, it can make sense to provide entry points for 127 both of them. 129 In addition, while both documentation and descriptions may be 130 provided as part of a Web service, there may be other information as 131 well. Generally speaking, a Web service may have any metadata/ 132 resources associated with it (with documentation/description just 133 being two specific kinds of resource). If there is a way how all of 134 these metadata/resources are represented, then it should be possible 135 to discover such a resource of general Web service metadata. 137 In addition to these resources about mostly static aspects of a Web 138 service, this memo also defines a link relation that allows providers 139 of a Web service to link to a resource that represents status 140 information about the service. This information often represents 141 operational information that allows service consumers to retrieve 142 information about "service health" and related issues. 144 This memo places no constraints on the specific representations used 145 for all of these resources. It simply allows providers of a Web 146 service to make the documentation, description, metadata, and status 147 of their services discoverable, and defines link relations that serve 148 that purpose. 150 2. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in RFC 2119 [RFC2119]. 156 3. Web Services 158 "Web Services" or "Web APIs" (sometimes also referred to as "HTTP 159 API" or "REST API") are a way to expose information and services on 160 the Web. Following the principles of Web architecture 161 [W3C.REC-webarch-20041215], they expose URI-identified resources, 162 which are then accessed and transferred using a specific 163 representation. Many services use representations that contain 164 links, and often these links are typed links. 166 Using typed links, resources can identify relationship types to other 167 resources. RFC 8288 [RFC8288] establishes a framework of registered 168 link relation types, which are identified by simple strings and 169 registered in an IANA registry. Any resource that supports typed 170 links according to RFC 8288 can then use these identifiers to 171 represent resource relationships on the Web without having to re- 172 invent registered relation types. 174 In recent years, Web services as well as their documentation and 175 description languages have gained popularity, due to the general 176 popularity of the Web as a platform for providing information and 177 services. However, the design of documentation and description 178 languages varies with a number of factors, such as the general 179 application domain, the preferred application data model, and the 180 preferred approach for exposing services. 182 This specification allows service providers to use a unified way to 183 link to service documentation and/or description. This link should 184 not make any assumptions about the provided type of documentation 185 and/or description, so that service providers can choose the ones 186 that best fit their services and needs. 188 This specification also allows service providers to link to general 189 service metadata, which as one part of it may have links to 190 documentation and/or description, but potentially can have other 191 information about a service as well, such as deployment or 192 operational information. 194 3.1. Documenting Web Services 196 In the context of this specification, "documentation" refers to 197 information that is primarily intended for human consumption. 198 Typical representations for this kind of documentation are HTML and 199 PDF. 201 Documentation is often structured, but the exact kind of 202 documentation structure depends on the structure of the service that 203 is documented, as well as on the specific way in which the 204 documentation authors choose to document it. 206 3.2. Describing Web Services 208 In the context of this specification, "description" refers to 209 information that is primarily intended for machine consumption. 210 Typical representations for this are dictated by the technology 211 underlying the service itself, which means that in today's technology 212 landscape, description formats exist that are based on XML, JSON, 213 RDF, and a variety of other structured data models. Also, in each of 214 those technologies, there may be a variety of languages that are 215 defined to achieve the same general purpose of describing a Web 216 service. 218 Descriptions are always structured, but the structuring principles 219 depend on the nature of the described service. For example, one of 220 the earlier service description approaches, the Web Services 221 Description Language (WSDL), uses "operations" as its core concept, 222 which are essentially identical to function calls, because the 223 underlying model is based on that of the Remote Procedure Call (RPC) 224 model. Other description languages for non-RPC approaches to 225 services will use different structuring approaches, such as 226 structuring service descriptions by URIs and/or URI patterns. 228 3.3. Unified Documentation/Description 230 If service providers use an approach where there is no distinction of 231 service documentation Section 3.1 and service description 232 Section 3.2, then they may not feel the need to use two separate 233 links. In such a case, an alternative approach is to use the 234 "service" link relation type, which has no indication of whether it 235 links to documentation or description, and thus may be better fit if 236 no such differentiation is required. 238 4. Link Relations for Web Services 240 In order to allow Web services to represent the relation of 241 individual resources to service documentation/description and 242 metadata, this specification introduces and registers three new link 243 relation types. 245 4.1. The service-doc Link Relation Type 247 The "service-doc" link relation type is used to represent the fact 248 that a resource is part of a bigger set of resources that are 249 documented at a specific URI. The target resource is expected to 250 provide documentation that is primarily intended for human 251 consumption. 253 4.2. The service-desc Link Relation Type 255 The "service-desc" link relation type is used to represent the fact 256 that a resource is part of a bigger set of resources that are 257 described at a specific URI. The target resource is expected to 258 provide a service description that is primarily intended for machine 259 consumption. In many cases, it is provided in a representation that 260 is consumed by tools, code libraries, or similar components. 262 4.3. The service-meta Link Relation Type 264 The "service-meta" link relation type is used to link to available 265 metadata for the service context of a resource. Service metadata is 266 any kind of data that may be of interest to existing or potential 267 service users, with documentation/description only being two possible 268 facets of service metadata. The target resource is expected to 269 provide a service description that is primarily intended for machine 270 consumption. In many cases, it is provided in a representation that 271 is consumed by tools, code libraries, or similar components. 273 Since service metadata can be for many different purposes, and use 274 many different representations, it may make sense for representations 275 using the "service-meta" link relation to add additional hints about 276 the specific kind or format of metadata that is being linked. This 277 definition of the "service-meta" link relation makes no specific 278 assumptions about how these link hints will be represented, and the 279 specific mechanism will depend on the context where the "service- 280 meta" link relation is being used. 282 5. Web Service Status Resources 284 Web services providing access to a set of resources often are hosted 285 and operated in an environment for which status information may be 286 available. This information may be as simple as confirming that a 287 service is operational, or may provide additional information about 288 different aspects of a service, and/or a history of status 289 information, possibly listing incidents and their resolution. 291 The "status" link relation type can be used to link to such a status 292 resource, allowing service consumers to retrieve status information 293 about a Web service's status. Such a link may not be available for 294 and from all resources provided by a Web service, but from key 295 resources such as a Web service's metadata resource and/or a 296 service's home resource [I-D.nottingham-json-home]. 298 This memo does not restrict the representation of a status resource 299 in any way. It may be primarily focused on human or machine 300 consumption, or a combination of both. It may be a simple "traffic 301 light" indicator for service health, or a more sophisticated 302 representation conveying more detailed information such as service 303 subsystems and/or a status history. 305 6. IANA Considerations 307 The link relation types below have been registered by IANA per 308 Section 4.2 of RFC 8288 [RFC8288]: 310 6.1. Link Relation Type: service-doc 312 Relation Name: service-doc 314 Description: Linking to service documentation that is primarily 315 intended for human consumption. 317 Reference: [[ This document ]] 319 6.2. Link Relation Type: service-desc 321 Relation Name: service-desc 323 Description: Linking to service description that is primarily 324 intended for consumption by machines. 326 Reference: [[ This document ]] 328 6.3. Link Relation Type: service-meta 330 Relation Name: service-meta 332 Description: Linking to service metadata that is primarily 333 intended for consumption by machines. 335 Reference: [[ This document ]] 337 6.4. Link Relation Type: status 339 Relation Name: status 341 Description: Linking to a resource that represents the status of a 342 Web service or API. 344 Reference: [[ This document ]] 346 7. Security Considerations 348 ... 350 8. References 352 8.1. Normative References 354 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 355 Requirement Levels", RFC 2119, March 1997. 357 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 358 DOI 10.17487/RFC8288, October 2017, 359 . 361 8.2. Informative References 363 [I-D.nottingham-json-home] 364 Nottingham, M., "Home Documents for HTTP APIs", draft- 365 nottingham-json-home-04 (work in progress), May 2016. 367 [W3C.REC-webarch-20041215] 368 Jacobs, I. and N. Walsh, "Architecture of the World Wide 369 Web, Volume One", World Wide Web Consortium 370 Recommendation REC-webarch-20041215, December 2004, 371 . 373 Appendix A. Acknowledgements 375 Thanks for comments and suggestions provided by Mike Amundsen, Oliver 376 Gierke, Sebastien Lambla, and Darrell Miller. 378 Author's Address 380 Erik Wilde 381 CA Technologies 383 Email: erik.wilde@dret.net 384 URI: http://dret.net/netdret/