idnits 2.17.1 draft-wilde-service-link-rel-10.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 date (January 11, 2019) is 1932 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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 January 11, 2019 4 Intended status: Informational 5 Expires: July 15, 2019 7 Link Relation Types for Web Services 8 draft-wilde-service-link-rel-10 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 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on July 15, 2019. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Web Services . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.1. Documenting Web Services . . . . . . . . . . . . . . . . 5 62 3.2. Describing Web Services . . . . . . . . . . . . . . . . . 5 63 3.3. Unified Documentation/Description . . . . . . . . . . . . 5 64 4. Link Relations for Web Services . . . . . . . . . . . . . . . 6 65 4.1. The service-doc Link Relation Type . . . . . . . . . . . 6 66 4.2. The service-desc Link Relation Type . . . . . . . . . . . 6 67 4.3. The service-meta Link Relation Type . . . . . . . . . . . 6 68 5. Web Service Status Resources . . . . . . . . . . . . . . . . 7 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 7 71 6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7 72 6.3. Link Relation Type: service-meta . . . . . . . . . . . . 8 73 6.4. Link Relation Type: status . . . . . . . . . . . . . . . 8 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 77 8.2. Informative References . . . . . . . . . . . . . . . . . 9 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 81 1. Introduction 83 One of the defining aspects of the Web is that it is possible to 84 interact with Web resources without any prior knowledge of the 85 specifics of the resource. Following Web Architecture 86 [W3C.REC-webarch-20041215] by using URIs, HTTP, and media types, the 87 Web's uniform interface allows interactions with resources without 88 the more complex binding procedures often necessary with other 89 approaches. 91 Many resources on the Web are provided as part of a set of resources 92 that are referred to as a "Web Service" or a "Web API". In many 93 cases, these services or APIs are defined and managed as a whole, and 94 it may be desirable for clients to be able to discover this service 95 information. 97 Service information that provides information on how to use service 98 resources can be broadly separated into two categories: One category 99 is primarily targeted for human users and often uses generic 100 representations for human readable documents, such as HTML or PDF. 101 The other category is structured information that follows some more 102 formalized description model, and is primarily intended for 103 consumption by machines, for example for tools and code libraries. 105 In the context of this memo, the human-oriented variant is referred 106 to as "documentation", and the machine-oriented variant is referred 107 to as "description". 109 These two categories are not necessarily mutually exclusive, as there 110 are representations that have been proposed that are intended for 111 both human consumption and interpretation by machine clients. In 112 addition, a typical pattern for service documentation/description is 113 that there is human-oriented high-level documentation that is 114 intended to put a service in context and explain the general model, 115 which is complemented by a machine-level description that is intended 116 as a detailed technical description of the service. These two 117 resources could be interlinked, but since they are intended for 118 different audiences, it can make sense to provide entry points for 119 both of them. 121 In addition, while both documentation and descriptions may be 122 provided as part of a Web service, there may be other information as 123 well. Generally speaking, a Web service may have any metadata/ 124 resources associated with it (with documentation/description just 125 being two specific kinds of resource). If there is a way how all of 126 these metadata/resources are represented, then it should be possible 127 to discover such a resource providing access to general Web service 128 metadata. 130 In addition to these resources about mostly static aspects of a Web 131 service, this memo also 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 This memo places no constraints on the specific representations used 138 for all of these resources. It simply allows providers of a Web 139 service to make the documentation, description, metadata, and status 140 of their services discoverable, and defines link relations that serve 141 that purpose. 143 2. Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in BCP 148 14 [RFC2119] [RFC8174] when, and only when, they appear in all 149 capitals, as shown here. 151 3. Web Services 153 "Web Services" or "Web APIs" (sometimes also referred to as "HTTP 154 API" or "REST API") are a way to expose information and services on 155 the Web. Following the principles of Web architecture 156 [W3C.REC-webarch-20041215], they expose URI-identified resources, 157 which are then accessed and transferred using a specific 158 representation. Many services use representations that contain 159 links, and often these links are typed links. 161 Using typed links, resources can identify relationship types to other 162 resources. RFC 8288 [RFC8288] establishes a framework of registered 163 link relation types, which are identified by simple strings and 164 registered in an IANA registry. Any resource that supports typed 165 links according to RFC 8288 can then use these identifiers to 166 represent resource relationships on the Web without having to re- 167 invent registered relation types. 169 In recent years, Web services as well as their documentation and 170 description languages have gained popularity, due to the general 171 popularity of the Web as a platform for providing information and 172 services. However, the design of documentation and description 173 languages varies with a number of factors, such as the general 174 application domain, the preferred application data model, and the 175 preferred approach for exposing services. 177 This specification allows service providers to use a unified way to 178 link to service documentation and/or description. This link should 179 not make any assumptions about the provided type of documentation 180 and/or description, so that service providers can choose the ones 181 that best fit their services and needs. 183 This specification also allows service providers to link to general 184 service metadata, which as one part of it may have links to 185 documentation and/or description, but potentially can have other 186 information about a service as well, such as deployment or 187 operational information. 189 3.1. Documenting Web Services 191 In the context of this specification, "documentation" refers to 192 information that is primarily intended for human consumption. 193 Typical representations for this kind of documentation are HTML and 194 PDF. 196 Documentation is often structured, but the exact kind of 197 documentation structure depends on the structure of the service that 198 is documented, as well as on the specific way in which the 199 documentation authors choose to document it. 201 3.2. Describing Web Services 203 In the context of this specification, "description" refers to 204 information that is primarily intended for machine consumption. 205 Typical representations for this are dictated by the technology 206 underlying the service itself, which means that in today's technology 207 landscape, description formats exist that are based on XML, JSON, 208 RDF, and a variety of other structured data models. Also, in each of 209 those technologies, there may be a variety of languages that are 210 defined to achieve the same general purpose of describing a Web 211 service. 213 Descriptions are always structured, but the structuring principles 214 depend on the nature of the described service. For example, one of 215 the earlier service description approaches, the Web Services 216 Description Language (WSDL), uses "operations" as its core concept, 217 which are essentially identical to function calls, because the 218 underlying model is based on that of the Remote Procedure Call (RPC) 219 model. Other description languages for non-RPC approaches to 220 services will use different structuring approaches, such as 221 structuring service descriptions by URIs and/or URI patterns. 223 3.3. Unified Documentation/Description 225 If service providers use an approach where there is no distinction 226 between service documentation (Section 3.1) and service description 227 (Section 3.2), then they may not feel the need to use two separate 228 links. In such a case, an alternative approach is to use the 229 previously defined "service" link relation type [RFC5023], which has 230 no indication of whether it links to documentation or description, 231 and thus may be a better fit if no such differentiation is required. 233 4. Link Relations for Web Services 235 In order to allow Web services to represent the relation of 236 individual resources to service documentation/description and 237 metadata, this specification introduces and registers three new link 238 relation types. 240 4.1. The service-doc Link Relation Type 242 The "service-doc" link relation type is used to represent the fact 243 that a resource or a set of resources are documented at a specific 244 URI. The target resource is expected to provide documentation that 245 is primarily intended for human consumption. 247 4.2. The service-desc Link Relation Type 249 The "service-desc" link relation type is used to represent the fact 250 that a resource or a set of resources are described at a specific 251 URI. The target resource is expected to provide a service 252 description that is primarily intended for machine consumption. In 253 many cases, it is provided in a representation that is consumed by 254 tools, code libraries, or similar components. 256 4.3. The service-meta Link Relation Type 258 The "service-meta" link relation type is used to link to available 259 metadata for the service context of a resource. Service metadata is 260 any kind of data that may be of interest to existing or potential 261 service users, with documentation/description only being two possible 262 facets of service metadata. The target resource is expected to 263 provide a representation that is primarily intended for machine 264 consumption. In many cases, it is provided in a representation that 265 is consumed by tools, code libraries, or similar components. 267 Since service metadata can be for many different purposes, and use 268 many different representations, it may make sense for representations 269 using the "service-meta" link relation to add additional hints about 270 the specific kind or format of metadata that is being linked. This 271 definition of the "service-meta" link relation makes no specific 272 assumptions about how these link hints will be represented, and the 273 specific mechanism will depend on the context where the "service- 274 meta" link relation is being used. 276 One example for this is that a "service-desc" link may identify an 277 OpenAPI description, which is supposed to be the machine-readable 278 description of a Web API. A "service-meta" link may identify a 279 resource that contains additional metadata about the Web API, such as 280 labels that classify the API according to a labeling scheme, and a 281 privacy policy that makes statements about how the Web API manages 282 personally identifiable information. 284 5. Web Service Status Resources 286 Web services providing access to one or more resources often are 287 hosted and operated in an environment for which status information 288 may be available. This information may be as simple as confirming 289 that a service is operational, or may provide additional information 290 about different aspects of a service, and/or a history of status 291 information, possibly listing incidents and their resolution. 293 The "status" link relation type can be used to link to such a status 294 resource, allowing service consumers to retrieve status information 295 about a Web service's status. Such a link may not be available for 296 and from all resources provided by a Web service, but from key 297 resources such as a Web service's metadata resource and/or a 298 service's home resource (i.e., a resource analogous to the home page 299 of a Web site). 301 This memo does not restrict the representation of a status resource 302 in any way. It may be primarily focused on human or machine 303 consumption, or a combination of both. It may be a simple "traffic 304 light" indicator for service health, or a more sophisticated 305 representation conveying more detailed information such as service 306 subsystems and/or a status history. 308 6. IANA Considerations 310 The link relation types below have been registered by IANA per 311 Section 4.2 of RFC 8288 [RFC8288]: 313 6.1. Link Relation Type: service-doc 315 Relation Name: service-doc 317 Description: Identifies service documentation for the context that 318 is primarily intended for human consumption. 320 Reference: [[ This document ]] 322 6.2. Link Relation Type: service-desc 324 Relation Name: service-desc 326 Description: Identifies service description for the context that 327 is primarily intended for consumption by machines. 329 Reference: [[ This document ]] 331 6.3. Link Relation Type: service-meta 333 Relation Name: service-meta 335 Description: Identifies general metadata for the context that is 336 primarily intended for consumption by machines. 338 Reference: [[ This document ]] 340 6.4. Link Relation Type: status 342 Relation Name: status 344 Description: Identifies a resource that represents the context's 345 status. 347 Reference: [[ This document ]] 349 7. Security Considerations 351 Web service providers should be aware that service descriptions and 352 documentation may be used by attackers to gain additional information 353 about a service (and in particular its implementation), and to test 354 for known security issues. It may thus be advisable to keep service 355 descriptions and documentation to those aspects of a service that are 356 necessary to use the service, and to exclude any details that are not 357 necessary for using the service. 359 Another potential security issue for Web service providers is that 360 publishing service descriptions and documentation may generally allow 361 clients (both malicious and otherwise) a more automated and 362 systematic access to a service. It may therefore be possible that 363 more of a service's potential vulnerabilities are made easier to find 364 and exploit, or simply that a service might receive more load because 365 it is accessed by automated clients. 367 Web service consumers should be aware that service descriptions and 368 documentation can be out of sync or simply incorrect. Blindly 369 trusting service descriptions and documentation (in particular when 370 descriptions are retrieved and interpreted programmatically) is not a 371 safe practice. Web service consumers SHOULD always assume that 372 service descriptions and documentation may be incorrect, and SHOULD 373 therefore be prepared to handle errors at runtime. 375 8. References 377 8.1. Normative References 379 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 380 Requirement Levels", RFC 2119, March 1997. 382 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 383 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 384 May 2017, . 386 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 387 DOI 10.17487/RFC8288, October 2017, 388 . 390 8.2. Informative References 392 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 393 Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, 394 October 2007, . 396 [W3C.REC-webarch-20041215] 397 Jacobs, I. and N. Walsh, "Architecture of the World Wide 398 Web, Volume One", World Wide Web Consortium 399 Recommendation REC-webarch-20041215, December 2004, 400 . 402 Appendix A. Acknowledgements 404 Thanks for comments and suggestions provided by Mike Amundsen, Ben 405 Campbell, Alissa Cooper, Oliver Gierke, Benjamin Kaduk, Sebastien 406 Lambla, Darrell Miller, and Adam Roach. 408 Author's Address 410 Erik Wilde 412 Email: erik.wilde@dret.net 413 URI: http://dret.net/netdret/