RFC 8631

Link Relation Types for Web Services

📅 published July 2019, from ietf

Okay bestie, let's get into it! This doc is from the IETF, which is the group that writes the rules for how the Internet works 🌐. It's an Informational RFC, which means it's sharing good ideas and best practices. It's not a binding Internet Standards Track spec 💅. It was written by E. Wilde and published in July 2019, and the ISSN is 2070-1721 ✨. Its header doesn't list any RFC that it obsoletes or updates. This is Part 1 of 2, so there's more coming 🧚

Abstract ✨

Okay so, tons of resources on the Web come in sets that one service provider manages together. We usually call those sets "Web services" or "Web APIs" 🌸. This spec defines link relations that connect a Web service or API to resources with its docs, descriptions, metadata, or status info. Docs are mostly for humans to read, and descriptions are mostly for machines to use 🤖. Metadata tells you about the service's context 💜. The spec also defines a link relation for status resources, which show info about whether the service is healthy 🩺.

Status of This Memo 📜

This document is not an Internet Standards Track specification. It's published for informational purposes 🎀.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, and it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every doc the IESG approves is a candidate for any level of Internet Standard, so check Section 2 of RFC 7841 for that 🙈.

You can find the current status of this document, any errata, and how to send feedback at https://www.rfc-editor.org/info/rfc8631 🦋.

Copyright (c) 2019 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, since 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 they're provided without warranty as described in the Simplified BSD License 💖.

Table of Contents 🗂️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
3.  Web Services  . . . . . . . . . . . . . . . . . . . . . . . .   4
  3.1.  Documenting Web Services  . . . . . . . . . . . . . . . .   5
  3.2.  Describing Web Services . . . . . . . . . . . . . . . . .   5
  3.3.  Unified Documentation/Description . . . . . . . . . . . .   5
4.  Link Relations for Web Services . . . . . . . . . . . . . . .   5
  4.1.  The service-doc Link Relation Type  . . . . . . . . . . .   6
  4.2.  The service-desc Link Relation Type . . . . . . . . . . .   6
  4.3.  The service-meta Link Relation Type . . . . . . . . . . .   6
5.  Web Service Status Resources  . . . . . . . . . . . . . . . .   7
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
  6.1.  Link Relation Type: service-doc . . . . . . . . . . . . .   7
  6.2.  Link Relation Type: service-desc  . . . . . . . . . . . .   7
  6.3.  Link Relation Type: service-meta  . . . . . . . . . . . .   8
  6.4.  Link Relation Type: status  . . . . . . . . . . . . . . .   8
7.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   9
  8.1.  Normative References  . . . . . . . . . . . . . . . . . .   9
  8.2.  Informative References  . . . . . . . . . . . . . . . . .   9
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   9
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

1. Introduction 🌈

One of the defining things about the Web is that you can interact with Web resources without knowing the specifics of the resource beforehand. It's giving freedom 🦋. This follows the practices in Web architecture [W3C.REC-webarch-20041215], using URIs, HTTP, and media types. The Web's uniform interface lets you interact with resources without the more complicated binding procedures that other approaches often need 💅.

Lots of resources on the Web are part of a set that people call a "Web service" or a "Web API" 🌸. A lot of the time, these services or APIs are defined and managed as a whole, so it makes sense for clients to be able to discover this service information 🔍.

Service information that explains how to use service resources falls into two big buckets 🪣. The first bucket is for humans, and it usually uses generic formats for readable docs, like HTML or PDF 📄. The second bucket is structured info that follows a more formal description model, made mostly for machines, like tools and code libraries 🛠️.

In this memo, the human-oriented one is called "documentation", and the machine-oriented one is called "description" 💜.

These two buckets aren't totally separate, because some representations are made for both humans and machine clients to read 👀. Also, a super common pattern is having high-level, human-friendly docs that put the service in context and explain the general model. Those get paired with machine-level descriptions that are detailed technical breakdowns of the service ✨. These two could link to each other, but since they're for different audiences, it can make sense to give each one its own entry point 🧚.

Also, docs and descriptions aren't the only things a Web service might have. A Web service can have any metadata or resources attached to it (docs and descriptions are just two specific kinds of resources) 🎀. If there's a way to represent all of that metadata and resources, then it should be possible to find a resource that gives you access to the general Web service metadata 🫶.

On top of these mostly static parts of a Web service, this memo also defines a link relation. It lets providers link to a resource that shows status info about the service 🚦. That info is often operational stuff that lets consumers check "service health" and related issues 🩺.

This memo doesn't put any limits on the specific representations used for these resources 🌸. It just lets providers make their service's docs, descriptions, metadata, and status discoverable, and it defines the link relations that do that job 💖.

2. Terminology 📚

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🔥. So if you see them in lowercase, they're just regular words, no cap 💅.

3. Web Services 🧚

"Web Services" or "Web APIs" (sometimes also called "HTTP API" or "REST API") expose information and services on the Web 🌐. Following the principles of Web architecture [W3C.REC-webarch-20041215], they expose URI-identified resources. Those get accessed and transferred using a specific representation 🎁. A lot of services use representations that contain links, and those links are often typed links 🔗.

With typed links, resources can say what kind of relationship they have with other resources 💜. RFC 8288 [RFC8288] sets up a framework of registered link relation types. They're identified by simple strings and listed in an IANA registry 📋. Any resource that supports typed links according to RFC 8288 can use these identifiers to show resource relationships on the Web, so nobody has to reinvent relation types that already exist 🙌.

Web services, and their documentation and description languages, have gotten super popular in recent years, since the Web is such a popular platform for sharing info and services 📈. But the design of documentation and description languages changes depending on things like the application domain, the preferred data model, and the preferred way of exposing services 🌈.

This spec lets service providers use one unified method to link to service documentation and/or descriptions 🦋. That link should not make any assumptions about what kind of documentation and/or descriptions are provided, so providers can pick the ones that best fit their services and needs 💅.

This spec also lets service providers link to general service metadata ✨. Part of that metadata can have links to documentation and/or descriptions, plus other info about the service, like deployment or operational details 🛠️.

3.1. Documenting Web Services 📖

In this spec, "documentation" means info that's mainly meant for humans to read 🙋‍♀️. Typical representations of this kind of documentation are HTML and PDF 📄.

Documentation is often structured, but how it's structured depends on the structure of the service in question, plus the way the authors choose to present it 🎀.

3.2. Describing Web Services 🤖

In this spec, "description" means info that's mainly meant for machines to consume 💻. The typical representations are decided by the technology the service is built on. That means description formats in today's tech landscape are based on XML, JSON, Resource Description Framework (RDF), and a bunch of other structured data models 🌸. Within each of those technologies, there can be multiple languages that serve the same general purpose of describing a Web service 🫧.

Descriptions are always structured, but the structuring principles depend on the nature of the described service 🧩. For example, the Web Services Description Language (WSDL) is one of the earlier service description approaches, and it uses "operations" as its core concept 📞. Those are basically the same as function calls, because the underlying model is based on the Remote Procedure Call (RPC) model 💀. Other description languages for non-RPC approaches to services use different structuring approaches, like structuring service descriptions by URIs and/or URI patterns 🔗.

3.3. Unified Documentation/Description 🫶

If a service provider uses an approach where there's no difference between service documentation (Section 3.1) and service description (Section 3.2), then they might not feel the need for two separate links 🙈. In that case, the alternative is to use the "service" link relation type that was defined earlier [RFC5023] 🎀. That one doesn't say whether it links to documentation or description, so it might be a better fit if you don't need to tell them apart 💜.

Part 1 done! 🌿 Part 2 is coming with Section 4 and beyond, so stay tuned, bestie 💖✨

okay so bestie, to let Web services show how a resource connects to its docs, its description, and its metadata, this spec introduces and registers three brand-new link relation types 💅🔥

The service-doc link relation type says that a resource or a set of resources is documented at a specific URI. The target is expected to provide documentation that's mainly for human eyes 🎀

The service-desc link relation type says that a resource or a set of resources is described at a specific URI. The target is expected to provide a service description that's mainly for machines 💜 A lot of the time it comes in a representation that tools, code libraries, or similar components consume ⚙️✨

The service-meta link relation type is used to link to available metadata for the service context of a resource. Service metadata is any kind of data that might interest existing or potential service users, and documentation and description are just two possible facets of it 🌈 The target is expected to provide a representation that's mainly for machine consumption. Often it's provided in a representation that tools, code libraries, or similar components consume 🫶

Service metadata can have tons of different purposes and use tons of different representations, so it may make sense for representations using the service-meta link relation to offer extra hints about the specific kind or format of metadata being linked 👀

This definition of the service-meta link relation makes no specific assumptions about how these link hints get represented. The specific mechanism depends on the context where the service-meta link relation is being used 🍓

One example: a service-desc link may identify an OpenAPI description, which is supposed to be the machine-readable description of a Web API. A service-meta link may identify a resource that contains extra metadata about that Web API, like labels that classify the API under a labeling scheme, and a privacy policy that explains how the Web API handles personally identifiable information 🔐💅

5. Web Service Status Resources 🚦

Web services that give access to one or more resources are often hosted and operated in an environment where status information may be available 🏠 That info can be as simple as confirming that a service is operational 🟢 Or it can give more detail about different aspects of a service, plus a history of status information, possibly listing incidents and how they were resolved 📜

The status link relation type can be used to link to such a status resource, so service consumers can retrieve info about a Web service's status 👑 A link like that isn't necessarily available for, or from, every resource a Web service provides. It's usually only for key resources, like a Web service's metadata resource and/or a service's home resource (basically the Web equivalent of a website's home page) 🏡

This memo doesn't restrict the representation of a status resource in any way 🙌 It can be mainly focused on humans, mainly on machines, or a mix of both 🤝 It can be a simple "traffic light" indicator for service health, or a fancier representation with more detailed info, like service subsystems and/or a status history 🚥✨

6. IANA Considerations 📋

The link relation types below have been registered by IANA per Section 4.2 of RFC 8288 [RFC8288] 🎀

Relation Name:  service-doc

Description:  Identifies service documentation for the context that is
   primarily intended for human consumption.

Reference:  RFC 8631
Relation Name:  service-desc

Description:  Identifies service description for the context that is
   primarily intended for consumption by machines.

Reference:  RFC 8631
Relation Name:  service-meta

Description:  Identifies general metadata for the context that is
   primarily intended for consumption by machines.

Reference:  RFC 8631
Relation Name:  status

Description:  Identifies a resource that represents the context's
   status.

Reference:  RFC 8631

7. Security Considerations 🔐

Web service providers, this one's for you 🫢 Service descriptions and documentation can be used by attackers to learn more about a service (especially its implementation) and to test for known security issues 😱 So it may be a good idea to limit service descriptions and documentation to the aspects of a service that are necessary, and to leave out any details that aren't needed to use the service 🛡️

Another potential security issue for providers: publishing service descriptions and documentation may give clients (both the malicious kind and the regular kind) more automated and systematic access to a service 🤖 That means more of a service's potential vulnerabilities could be made easier to find and exploit, or a service might simply get more load from automated clients 💀 It may therefore be possible that more of a service's potential vulnerabilities are made easier to find and exploit, or that a service receives more load because it's accessed by automated clients 📈

Web service consumers, you need to know this too 🙈 Service descriptions and documentation can be out of sync or just plain incorrect 😬 Blindly trusting service descriptions and documentation (especially when they're retrieved and interpreted programmatically) is not a safe practice 🚨 Web service consumers SHOULD always assume that service descriptions and documentation may be incorrect, and they SHOULD therefore be prepared to handle errors at runtime 🫶💜

8. References 📚

8.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8288]  Nottingham, M., "Web Linking", RFC 8288,
           DOI 10.17487/RFC8288, October 2017,
           <https://www.rfc-editor.org/info/rfc8288>.

8.2. Informative References

[RFC5023]  Gregorio, J., Ed. and B. de hOra, Ed., "The Atom
           Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023,
           October 2007, <https://www.rfc-editor.org/info/rfc5023>.

[W3C.REC-webarch-20041215]
           Jacobs, I. and N. Walsh, "Architecture of the World Wide
           Web, Volume One", World Wide Web Consortium
           Recommendation REC-webarch-20041215, December 2004,
           <http://www.w3.org/TR/2004/REC-webarch-20041215>.

Acknowledgements 🌸

Thanks to Mike Amundsen, Ben Campbell, Alissa Cooper, Oliver Gierke, Benjamin Kaduk, Sebastien Lambla, Darrell Miller, and Adam Roach for their comments and suggestions 🥹💖

Author's Address 🦋

Erik Wilde

Email: erik.wilde@dret.net
URI:   http://dret.net/netdret/
📦 where this page comes from