1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
|
<pre>Internet Engineering Task Force (IETF) E. Wilde
Request for Comments: 8631 July 2019
Category: Informational
ISSN: 2070-1721
<span class="h1">Link Relation Types for Web Services</span>
Abstract
Many resources provided on the Web are part of sets of resources that
are provided in a context that is managed by one particular service
provider. Often, these sets of resources are referred to as "Web
services" or "Web APIs". This specification defines link relations
that represent relationships from Web services or APIs to resources
that provide documentation, descriptions, metadata, or status
information for these resources. Documentation is primarily intended
for human consumers, whereas descriptions are primarily intended for
automated consumers. Metadata provides information about a service's
context. This specification also defines a link relation to identify
status resources that are used to represent information about service
status.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see <a href="./rfc7841#section-2">Section 2 of RFC 7841</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="https://www.rfc-editor.org/info/rfc8631">https://www.rfc-editor.org/info/rfc8631</a>.
<span class="grey">Wilde Informational [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="https://trustee.ietf.org/license-info">https://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as 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 are provided without warranty as
described in the Simplified BSD License.
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-2">2</a>. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-3">3</a>. Web Services . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-3.1">3.1</a>. Documenting Web Services . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-3.2">3.2</a>. Describing Web Services . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-3.3">3.3</a>. Unified Documentation/Description . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-4">4</a>. Link Relations for Web Services . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-4.1">4.1</a>. The service-doc Link Relation Type . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-4.2">4.2</a>. The service-desc Link Relation Type . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-4.3">4.3</a>. The service-meta Link Relation Type . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-5">5</a>. Web Service Status Resources . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6">6</a>. IANA Considerations . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6.1">6.1</a>. Link Relation Type: service-doc . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6.2">6.2</a>. Link Relation Type: service-desc . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6.3">6.3</a>. Link Relation Type: service-meta . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-6.4">6.4</a>. Link Relation Type: status . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-7">7</a>. Security Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-8">8</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-8.1">8.1</a>. Normative References . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-8.2">8.2</a>. Informative References . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<span class="grey">Wilde Informational [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
One of the defining aspects of the Web is that it is possible to
interact with Web resources without any prior knowledge of the
specifics of the resource. Following the practices described in Web
architecture [<a href="#ref-W3C.REC-webarch-20041215">W3C.REC-webarch-20041215</a>] by using URIs, HTTP, and
media types, the Web's uniform interface allows interactions with
resources without the more complex binding procedures often necessary
with other approaches.
Many resources on the Web are provided as part of a set of resources
that are referred to as a "Web service" or a "Web API". In many
cases, these services or APIs are defined and managed as a whole, and
it may be desirable for clients to be able to discover this service
information.
Service information that provides information on how to use service
resources can be broadly separated into two categories: One category
primarily targets human users and often uses generic representations
for human readable documents, such as HTML or PDF. The other
category is structured information that follows a more formalized
description model and is primarily intended for consumption by
machines -- for example, tools and code libraries.
In the context of this memo, the human-oriented variant is referred
to as "documentation", and the machine-oriented variant is referred
to as "description".
These two categories are not necessarily mutually exclusive, as
representations have been proposed that are intended for both human
consumption and interpretation by machine clients. In addition, a
typical pattern for service documentation/descriptions is that there
is human-oriented, high-level documentation that is intended to put a
service in context and explain the general model, which is
complemented by machine-level descriptions that are intended as
detailed technical descriptions of the service. These two resources
could be interlinked, but since they are intended for different
audiences, it can make sense to provide entry points for both of
them.
In addition, while both documentation and descriptions may be
provided as part of a Web service, there may be other information as
well. Generally speaking, a Web service may have any metadata/
resources associated with it (with documentation and descriptions
being two specific kinds of resources). If there is a way in which
all of these metadata/resources can be represented, then it should be
possible to find such a resource that provides access to general Web
service metadata.
<span class="grey">Wilde Informational [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
In addition to these resources about mostly static aspects of a Web
service, this memo also defines a link relation that allows providers
of a Web service to link to a resource that represents status
information about the service. This information often represents
operational information that allows service consumers to retrieve
information about "service health" and related issues.
This memo places no constraints on the specific representations used
for all of these resources. It simply allows providers of a Web
service to make the documentation, descriptions, metadata, and status
of their services discoverable and defines link relations that serve
that purpose.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Terminology</span>
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
<a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a> [<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>] [<a href="./rfc8174" title=""Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"">RFC8174</a>] when, and only when, they appear in all
capitals, as shown here.
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Web Services</span>
"Web Services" or "Web APIs" (sometimes also referred to as "HTTP
API" or "REST API") expose information and services on the Web.
Following the principles of Web architecture
[<a href="#ref-W3C.REC-webarch-20041215">W3C.REC-webarch-20041215</a>], they expose URI-identified resources,
which are then accessed and transferred using a specific
representation. Many services use representations that contain
links, and these links are often typed links.
Using typed links, resources can identify relationship types to other
resources. <a href="./rfc8288">RFC 8288</a> [<a href="./rfc8288" title=""Web Linking"">RFC8288</a>] establishes a framework of registered
link relation types, which are identified by simple strings and
registered in an IANA registry. Any resource that supports typed
links according to <a href="./rfc8288">RFC 8288</a> can then use these identifiers to
represent resource relationships on the Web without having to
reinvent registered relation types.
In recent years, Web services, as well as their documentation and
description languages, have gained popularity due to the general
popularity of the Web as a platform for providing information and
services. However, the design of documentation and description
languages varies according to a number of factors, such as the
general application domain, the preferred application data model, and
the preferred approach for exposing services.
<span class="grey">Wilde Informational [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
This specification allows service providers to use a unified method
to link to service documentation and/or descriptions. This link
should not make any assumptions about the provided type of
documentation and/or descriptions, so service providers can choose
those that best fit their services and needs.
This specification also allows service providers to link to general
service metadata. One part of the metadata may have links to
documentation and/or description as well as other information about a
service, such as deployment or operational information.
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Documenting Web Services</span>
In the context of this specification, "documentation" refers to
information that is primarily intended for human consumption.
Typical representations of this kind of documentation are HTML and
PDF.
Documentation is often structured, but its structure depends on the
structure of the service in question as well as the specific way in
which the authors choose to present it.
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Describing Web Services</span>
In the context of this specification, "description" refers to
information that is primarily intended for machine consumption.
Typical representations are dictated by the technology underlying the
service itself, which means that description formats in today's
technology landscape are based on XML, JSON, Resource Description
Framework (RDF), and a variety of other structured data models. In
each of those technologies, there may be a variety of languages
defined to 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, one of
the earlier service description approaches, the Web Services
Description Language (WSDL), uses "operations" as its core concept,
which are essentially identical to function calls because the
underlying model is based on the Remote Procedure Call (RPC) model.
Other description languages for non-RPC approaches to services will
use different structuring approaches, such as structuring service
descriptions by URIs and/or URI patterns.
<span class="grey">Wilde Informational [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
<span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Unified Documentation/Description</span>
If service providers use an approach where there is no distinction
between service documentation (<a href="#section-3.1">Section 3.1</a>) and service description
(<a href="#section-3.2">Section 3.2</a>), then they may not feel the need to use two separate
links. In such a case, an alternative approach is to use the
previously defined "service" link relation type [<a href="./rfc5023" title=""The Atom Publishing Protocol"">RFC5023</a>], which does
not indicate whether it links to documentation or description and
thus may be a better fit if no such differentiation is required.
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Link Relations for Web Services</span>
In order to allow Web services to represent the relation of
individual resources to service documentation/description and
metadata, this specification introduces and registers three new link
relation types.
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. The service-doc Link Relation Type</span>
The "service-doc" link relation type is used to represent the fact
that a resource or a set of resources is documented at a specific
URI. The target resource is expected to provide documentation that
is primarily intended for human consumption.
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. The service-desc Link Relation Type</span>
The "service-desc" link relation type is used to represent the fact
that a resource or a set of resources is described at a specific URI.
The target resource is expected to provide a service description that
is primarily intended for machine consumption. In many cases, it is
provided in a representation that is consumed by tools, code
libraries, or similar components.
<span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. The service-meta Link Relation Type</span>
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 may be of interest to existing or potential
service users, with documentation/description being only two possible
facets of service metadata. The target resource is expected to
provide a representation that is primarily intended for machine
consumption. In many cases, it is provided in a representation that
is consumed by tools, code libraries, or similar components.
Since service metadata can have many different purposes and use many
different representations, it may make sense for representations
using the "service-meta" link relation to offer additional hints
about the specific kind or format of metadata that is being linked.
<span class="grey">Wilde Informational [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
This definition of the "service-meta" link relation makes no specific
assumptions about how these link hints will be represented, and the
specific mechanism will depend on the context where the "service-
meta" link relation is being used.
One example is that 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 additional metadata about the Web API, such as labels that
classify the API according to a labeling scheme and a privacy policy
that makes statements about how the Web API manages personally
identifiable information.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Web Service Status Resources</span>
Web services providing access to one or more resources often are
hosted and operated in an environment for which status information
may be available. This information may be as simple as confirming
that a service is operational, or it may provide additional
information about different aspects of a service and/or a history of
status information, possibly listing incidents and their resolution.
The "status" link relation type can be used to link to such a status
resource, allowing service consumers to retrieve information about a
Web service's status. Such a link may not be available for and from
all resources provided by a Web service -- only from key resources
such as a Web service's metadata resource and/or a service's home
resource (i.e., a resource analogous to the home page of a Web site).
This memo does not restrict the representation of a status resource
in any way. It may be primarily focused on human or machine
consumption or a combination of both. It may be a simple "traffic
light" indicator for service health or a more sophisticated
representation conveying more detailed information, such as service
subsystems and/or a status history.
<span class="grey">Wilde Informational [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. IANA Considerations</span>
The link relation types below have been registered by IANA per
<a href="./rfc8288#section-4.2">Section 4.2 of RFC 8288</a> [<a href="./rfc8288" title=""Web Linking"">RFC8288</a>].
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Link Relation Type: service-doc</span>
Relation Name: service-doc
Description: Identifies service documentation for the context that
is primarily intended for human consumption.
Reference: <a href="./rfc8631">RFC 8631</a>
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Link Relation Type: service-desc</span>
Relation Name: service-desc
Description: Identifies service description for the context that is
primarily intended for consumption by machines.
Reference: <a href="./rfc8631">RFC 8631</a>
<span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a>. Link Relation Type: service-meta</span>
Relation Name: service-meta
Description: Identifies general metadata for the context that is
primarily intended for consumption by machines.
Reference: <a href="./rfc8631">RFC 8631</a>
<span class="h3"><a class="selflink" id="section-6.4" href="#section-6.4">6.4</a>. Link Relation Type: status</span>
Relation Name: status
Description: Identifies a resource that represents the context's
status.
Reference: <a href="./rfc8631">RFC 8631</a>
<span class="grey">Wilde Informational [Page 8]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Security Considerations</span>
Web service providers should be aware that service descriptions and
documentation may be used by attackers to gain additional information
about a service (particularly its implementation) and to test for
known security issues. It may thus be advisable to restrict service
descriptions and documentation to aspects of a service that are
necessary and to exclude any details that are not necessary for using
the service.
Another potential security issue for Web service providers is that
publishing service descriptions and documentation may generally allow
clients (both malicious and otherwise) more automated and systematic
access to a service. It may therefore be possible that more of a
service's potential vulnerabilities are made easier to find and
exploit or simply that a service might receive more load because it
is accessed by automated clients.
Web service consumers should be aware that service descriptions and
documentation can be out of sync or simply incorrect. Blindly
trusting service descriptions and documentation (particularly when
descriptions are retrieved and interpreted programmatically) is not a
safe practice. Web service consumers SHOULD always assume that
service descriptions and documentation may be incorrect and SHOULD
therefore be prepared to handle errors at runtime.
<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. References</span>
<span class="h3"><a class="selflink" id="section-8.1" href="#section-8.1">8.1</a>. Normative References</span>
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>,
DOI 10.17487/RFC2119, March 1997,
<<a href="https://www.rfc-editor.org/info/rfc2119">https://www.rfc-editor.org/info/rfc2119</a>>.
[<a id="ref-RFC8174">RFC8174</a>] Leiba, B., "Ambiguity of Uppercase vs Lowercase in <a href="./rfc2119">RFC</a>
<a href="./rfc2119">2119</a> Key Words", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc8174">RFC 8174</a>, DOI 10.17487/RFC8174,
May 2017, <<a href="https://www.rfc-editor.org/info/rfc8174">https://www.rfc-editor.org/info/rfc8174</a>>.
[<a id="ref-RFC8288">RFC8288</a>] Nottingham, M., "Web Linking", <a href="./rfc8288">RFC 8288</a>,
DOI 10.17487/RFC8288, October 2017,
<<a href="https://www.rfc-editor.org/info/rfc8288">https://www.rfc-editor.org/info/rfc8288</a>>.
<span class="grey">Wilde Informational [Page 9]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
<span class="grey"><a href="./rfc8631">RFC 8631</a> Link Relation Types for Web Services July 2019</span>
<span class="h3"><a class="selflink" id="section-8.2" href="#section-8.2">8.2</a>. Informative References</span>
[<a id="ref-RFC5023">RFC5023</a>] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom
Publishing Protocol", <a href="./rfc5023">RFC 5023</a>, DOI 10.17487/RFC5023,
October 2007, <<a href="https://www.rfc-editor.org/info/rfc5023">https://www.rfc-editor.org/info/rfc5023</a>>.
[<a id="ref-W3C.REC-webarch-20041215">W3C.REC-webarch-20041215</a>]
Jacobs, I. and N. Walsh, "Architecture of the World Wide
Web, Volume One", World Wide Web Consortium
Recommendation REC-webarch-20041215, December 2004,
<<a href="http://www.w3.org/TR/2004/REC-webarch-20041215">http://www.w3.org/TR/2004/REC-webarch-20041215</a>>.
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: <a href="http://dret.net/netdret/">http://dret.net/netdret/</a>
Wilde Informational [Page 10]
</pre>
|
