Home Documents for HTTP APIs

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 3 January 2025.¶

Copyright Notice

Copyright (c) 2024 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, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

It is becoming increasingly common to use HTTP [RFC7230] for applications other than traditional Web browsing. Such "HTTP APIs" are used to integrate processes on disparate systems, make information available to machines across the Internet, and as part of the implementation of "microservices."¶

By using HTTP, these applications realise a number of benefits, from message framing to caching, and well-defined semantics that are broadly understood and useful.¶

Often, these applications of HTTP are defined by documenting static URLs that clients need to know and servers need to implement. Any interaction outside of these bounds is uncharted territory.¶

For some applications, this approach brings issues, especially when the interface changes, either due to evolution, extension or drift between implementations. Furthermore, implementing more than one instance of interface can bring further issues, as different environments have different requirements.¶

The Web itself offers one way to address these issues, using links [RFC3986] to navigate between states. A link-driven application discovers relevant resources at run time, using a shared vocabulary of link relations [RFC8288] and internet media types [RFC6838] to support a "follow your nose" style of interaction -- just as a Web browser does to navigate the Web.¶

A client can then decide which resources to interact with "on the fly" based upon its capabilities (as described by link relations), and the server can safely add new resources and formats without disturbing clients that are not yet aware of them.¶

Doing so can provide any of a number of benefits, including:¶

• Extensibility - Because new server capabilities can be expressed as resources typed by link relations, new features can be layered in without introducing a new API version; clients will discover them in the home document. This promotes loose coupling between clients and servers.¶

• Evolvability - Likewise, interfaces can change gradually by introducing a new link relation and/or format while still supporting the old ones.¶

• Customisation - Home documents can be tailored for the client, allowing different classes of service or different client roles and permissions to be exposed naturally.¶

• Flexible deployment - Since URLs aren't baked into documentation, the server can choose what URLs to use for a given service.¶

• API mixing - Likewise, more than one API can be deployed on a given server, without fear of collisions.¶

Whether an application ought to use links in this fashion depends on how it is deployed; generally, the most benefit will be received when multiple instances of the service are deployed, possibly with different versions, and they are consumed by clients with different capabilities. In particular, Internet Standards that use HTTP as a substrate are likely to require the attributes described above.¶

This document defines a "home document" format using the JSON format [RFC7159] for APIs to use as a launching point for the interactions they offer, using links. Having a well-defined format for this purpose promotes good practice and development of tooling.¶

2. API Home Documents

An API Home Document (or "home document") uses the format described in [RFC7159] and has the media type "application/json-home".¶

Note: this media type is not final, and will change before final publication.¶

Its content consists of a root object with:¶

• A "resources" member, whose value is an object that describes the resources of the API. Its member names are link relation types (as defined by [RFC8288]), and their values are Resource Objects (Section 4).¶

• Optionally, a "api" member, whose value is an API Object (Section 3) that contains information about the API as a whole.¶

For example:¶

GET / HTTP/1.1
Host: example.org
Accept: application/json-home

HTTP/1.1 200 OK
Content-Type: application/json-home
Cache-Control: max-age=3600
Connection: close

{
  "api": {
    "title": "Example API",
    "links": {
      "author": "mailto:api-admin@example.com",
      "describedBy": "https://example.com/api-docs/"
    }
  },
  "resources": {
    "tag:me@example.com,2016:widgets": {
      "href": "/widgets/"
    },
    "tag:me@example.com,2016:widget": {
      "hrefTemplate": "/widgets/{widget_id}",
      "hrefVars": {
        "widget_id": "https://example.org/param/widget"
      },
      "hints": {
        "allow": ["GET", "PUT", "DELETE", "PATCH"],
        "formats": {
          "application/json": {}
        },
        "acceptPatch": ["application/json-patch+json"],
        "acceptRanges": ["bytes"]
      }
    }
  }
}

Here, we have a home document for the API "Example API", whose author can be contacted at the e-mail address "api-admin@example.com", and whose documentation is at "https://example.com/api-docs/".¶

It links to a resource "/widgets/" with the relation "tag:me@example.com,2016:widgets". It also links to an unknown number of resources with the relation type "tag:me@example.com,2016:widget" using a URI Template [RFC6570], along with a mapping of identifiers to a variable for use in that template.¶

It also gives several hints about interacting with the latter "widget" resources, including the HTTP methods usable with them, the PATCH and POST formats they accept, and the fact that they support partial requests [RFC7233] using the "bytes" range-specifier.¶

It gives no such hints about the "widgets" resource. This does not mean that it (for example) doesn't support any HTTP methods; it means that the client will need to discover this by interacting with the resource, and/or examining the documentation for its link relation type.¶

Effectively, this names a set of behaviors, as described by a resource object, with a link relation type. This means that several link relations might apply to a common base URL; e.g.:¶

{
  "resources": {
    "tag:me@example.com,2016:search-by-id": {
      "hrefTemplate": "/search?id={widget_id}",
      "hrefVars": {
        "widget_id": "https://example.org/param/widget_id"
      }
    },
    "tag:me@example.com,2016:search-by-name": {
      "hrefTemplate": "/search?name={widget_name}",
      "hrefVars": {
        "widget_name": "https://example.org/param/widget_name"
      }
    }
  }
}

Note that the examples above use both tag [RFC4151] and https [RFC7230] URIs; any URI scheme can be used to identify link relations and other artefacts in home documents. Typically, these are not links to be followed; they are only used to identify things.¶

3. API Objects

An API Object contains links to information about the API itself.¶

Two optional members are defined:¶

• "title" has a string value indicating the name of the API;¶

• "links" has an object value, whose member names are link relation types [RFC8288], and values are URLs [RFC3986]. The context of these links is the API home document as a whole.¶

No links are required to be conveyed, but APIs might benefit from setting the following:¶

• author - a suitable URL (e.g., mailto: or https:) for the author(s) of the API¶

• describedBy - a link to documentation for the API¶

• license - a link to the legal terms for using the API¶

Future members of the API Object MAY be defined by specifications that update this document.¶

4. Resource Objects

A Resource Object links to resources of the type indicated in their name using one of two mechanisms; either a direct link (in which case there is exactly one resource of that relation type associated with the API), or a templated link, in which case there are zero to many such resources.¶

Direct links are indicated with an "href" property, whose value is a URI [RFC3986].¶

Templated links are indicated with an "hrefTemplate" property, whose value is a URI Template [RFC6570]. When "hrefTemplate" is present, the Resource Object MUST have a "hrefVars" property; see "Resolving Templated Links".¶

Resource Objects MUST have exactly one of the "href" or "href-vars" properties.¶

In both forms, the links that "href" and "hrefTemplate" refer to are URI-references [RFC3986] whose base URI is that of the API Home Document itself.¶

Resource Objects MAY also have a "hints" property, whose value is an object that uses HTTP Link Hints (see [I-D.nottingham-link-hint]) as its properties.¶

  "https://example.org/rel/widget": {
    "hrefTemplate": "/widgets/{widget_id}",
    "hrefVars": {
      "widget_id": "https://example.org/param/widget"
    },
    "hints": {
      "allow": ["GET", "PUT", "DELETE", "PATCH"],
      "formats": {
        "application/json": {}
      },
      "acceptPatch": ["application/json-patch+json"],
      "acceptRanges": ["bytes"]
    }
  }

5. Discovering Home Documents

Home documents are useful starting points for interacting with APIs, both for using the API itself and for discovering additional information about the API. Home documents are distinct resources with their own URIs, and it is possible that home document resources are linked to from other resources, such as from (possibly select) resources of the API itself, or from resources that provide API directory or discovery services.¶

In these cases, the question is how to establish the link to a home document. This specification defines and registers a specific link relation type for this purpose, so that links to home documents can be made and identified by using this specific link relation type.¶

6. Security Considerations

Clients need to exercise care when using hints. For example, a naive client might send credentials to a server that uses the auth-req hint, without checking to see if those credentials are appropriate for that server.¶

7. IANA Considerations

Appendix A. Acknowledgements

Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze, Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik Wilde and Jorge Williams for their suggestions and feedback.¶

Appendix B. Creating and Serving Home Documents

When making an API home document available, there are a few things to keep in mind:¶

• A home document is best located at a memorable URI, because its URI will effectively become the URI for the API itself to clients.¶

• Home documents can be personalized, just as "normal" home pages can. For example, you might advertise different URIs, and/or different kinds of link relations, depending on the client's identity.¶

• Home documents ought to be assigned a freshness lifetime (e.g., "Cache-Control: max-age=3600") so that clients can cache them, to avoid having to fetch it every time the client interacts with the service.¶

• Custom link relation types, as well as the URIs for variables, should lead to documentation for those constructs.¶

Appendix C. Consuming Home Documents

Clients might use home documents in a variety of ways.¶

In the most common case -- actually consuming the API -- the client will scan the Resources Object for the link relation(s) that it is interested in, and then to interact with the resource(s) referred to. Resource Hints can be used to optimize communication with the client, as well as to inform as to the permissible actions (e.g., whether PUT is likely to be supported).¶

Note that the home document is a "living" document; it does not represent a "contract", but rather is expected to be inspected before each interaction. In particular, links from the home document MUST NOT be assumed to be valid beyond the freshness lifetime of the home document, as per HTTP's caching model [RFC7234].¶

As a result, clients ought to cache the home document (as per [RFC7234]), to avoid fetching it before every interaction (which would otherwise be required).¶

Likewise, a client encountering a 404 (Not Found) on a link is encouraged obtain a fresh copy of the home document, to assure that it is up-to-date.¶

Appendix D. Frequently Asked Questions

Author's Address