draft-inadarei-api-health-check-05.xml

<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.2.13 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc ipr="trust200902" docName="draft-inadarei-api-health-check-05" category="info">

  <front>
    <title>Health Check Response Format for HTTP APIs</title>

    <author initials="I." surname="Nadareishvili" fullname="Irakli Nadareishvili">
      <organization></organization>
      <address>
        <postal>
          <street>114 5th Avenue</street>
          <city>New York</city>
          <country>United States of America</country>
        </postal>
        <email>irakli@gmail.com</email>
        <uri>http://www.freshblurbs.com</uri>
      </address>
    </author>

    <date year="2020"/>

    <area>General</area>
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This document proposes a service health check response format for HTTP APIs.</t>



    </abstract>


    <note title="Note to Readers">


<t><spanx style="strong">RFC EDITOR: please remove this section before publication</spanx></t>

<t>The issues list for this draft can be found at <eref target="https://github.com/inadarei/rfc-healthcheck/issues">https://github.com/inadarei/rfc-healthcheck/issues</eref>.</t>

<t>The most recent draft is at <eref target="https://inadarei.github.io/rfc-healthcheck/">https://inadarei.github.io/rfc-healthcheck/</eref>.</t>

<t>Recent changes are listed at <eref target="https://github.com/inadarei/rfc-healthcheck/commits/master">https://github.com/inadarei/rfc-healthcheck/commits/master</eref>.</t>

<t>See also the draft’s current status in the IETF datatracker, at
<eref target="https://datatracker.ietf.org/doc/draft-inadarei-api-health-check/">https://datatracker.ietf.org/doc/draft-inadarei-api-health-check/</eref>.</t>


    </note>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>The vast majority of modern APIs driving data to web and mobile applications use
HTTP <xref target="RFC7230"/> as their protocol. The health and uptime of these APIs
determine availability of the applications themselves. In distributed systems
built with a number of APIs, understanding the health status of the APIs and
making corresponding decisions, for caching, failover or circuit-breaking, are
essential to the ability of providing highly-available solutions.</t>

<t>There exists a wide variety of operational software that relies on the ability
to read health check response of APIs. However, there is currently no standard
for the health check output response, so most applications either rely on the
basic level of information included in HTTP status codes <xref target="RFC7231"/> or use
task-specific formats.</t>

<t>Usage of task-specific or application-specific formats creates significant
challenges, disallowing any meaningful interoperability across different
implementations and between different tooling.</t>

<t>Standardizing a format for health checks can provide any of a number of
benefits, including:</t>

<t><list style="symbols">
  <t>Flexible deployment - since operational tooling and API clients can rely on
rich, uniform format, they can be safely combined and substituted as needed.</t>
  <t>Evolvability - new APIs, conforming to the standard, can safely be introduced
in any environment and ecosystem that also conforms to the same standard,
without costly coordination and testing requirements.</t>
</list></t>

<t>This document defines a “health check” format using the JSON format <xref target="RFC8259"/>
for APIs to use as a standard point for the health information they offer.
Having a well-defined format for this purpose promotes good practice and
tooling.</t>

</section>
<section anchor="notational-conventions" title="Notational Conventions">

<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in <xref target="RFC2119"/>.</t>

</section>
<section anchor="api-health-response" title="API Health Response">

<t>Health Check Response Format for HTTP APIs uses the JSON format described in
<xref target="RFC8259"/> and has the media type “application/health+json”.</t>

<t>Its content consists of a single mandatory root field (“status”) and several
optional fields:</t>

<section anchor="status" title="status">

<t>status: (required) indicates whether the service status is acceptable or not.
API publishers SHOULD use following values for the field:</t>

<t><list style="symbols">
  <t>“pass”: healthy (acceptable aliases: “ok” to support Node’s Terminus and
“up” for Java’s SpringBoot),</t>
  <t>“fail”: unhealthy (acceptable aliases: “error” to support Node’s Terminus and
“down” for Java’s SpringBoot), and</t>
  <t>“warn”: healthy, with some concerns.</t>
</list></t>

<t>The value of the status field is case-insensitive and is tightly related with
  the HTTP response code returned by the health endpoint. For “pass” status,
  HTTP response code in the 2xx-3xx range MUST be used. For “fail” status,
  HTTP response code in the 4xx-5xx range MUST be used. In case of the “warn”
  status, endpoints MUST return HTTP status in the 2xx-3xx range, and
  additional information SHOULD be provided, utilizing optional fields of the
  response.</t>

<t>A health endpoint is only meaningful in the context of the component it
  indicates the health of. It has no other meaning or purpose. As such, its
  health is a conduit to the health of the component. Clients SHOULD assume that
  the HTTP response code returned by the health endpoint is applicable to the
  entire component (e.g. a larger API or a microservice). This is compatible
  with the behavior that current infrastructural tooling expects:
  load-balancers, service discoveries and others, utilizing health-checks.</t>

</section>
<section anchor="version" title="version">

<t>version: (optional) public version of the service.</t>

</section>
<section anchor="releaseid" title="releaseId">

<t>releaseId: (optional) in well-designed APIs, backwards-compatible changes in
  the service should not update a version number. APIs usually change their
  version number as infrequently as possible, to preserve stable interface.
  However, implementation of an API may change much more frequently, which leads
  to the importance of having separate “release number” or “releaseId” that is
  different from the public version of the API.</t>

</section>
<section anchor="notes" title="notes">

<t>notes: (optional) array of notes relevant to current state of health</t>

</section>
<section anchor="output" title="output">

<t>output: (optional) raw error output, in case of “fail” or “warn” states. This
  field SHOULD be omitted for “pass” state.</t>

</section>
<section anchor="checks" title="checks">

<t>checks (optional) is an object that provides detailed health statuses of
additional downstream systems and endpoints which can affect the overall health
of the main API. Please refer to the “The Checks Object” section for more
information.</t>

</section>
<section anchor="links" title="links">

<t>links (optional) is an object containing link relations and URIs
<xref target="RFC3986"/> for external links that MAY contain more information about the
health of the endpoint. All values of this object SHALL be URIs. Keys MAY
also be URIs. Per web-linking standards <xref target="RFC8288"/> a link
relationship SHOULD either be a common/registered one or be indicated as a URI,
to avoid name clashes.  If a “self” link is provided, it MAY be used by clients
to check health via HTTP response code, as mentioned above.</t>

</section>
<section anchor="serviceid" title="serviceId">

<t>serviceId (optional) is a unique identifier of the service, in the application
scope.</t>

</section>
<section anchor="description" title="description">

<t>description (optional) is a human-friendly description of the service.</t>

</section>
</section>
<section anchor="the-checks-object" title="The Checks Object">

<t>The “checks” object MAY have a number of unique keys, one for each logical
downstream dependency or sub-component. Since each sub-component may be
backed by several nodes with varying health statuses, these keys point to arrays
of objects. In case of a single-node sub-component (or if presence of nodes is
not relevant), a single-element array SHOULD be used as the value, for
consistency.</t>

<t>The key identifying an element in the object SHOULD be a unique string within
the details section. It MAY have two parts: “{componentName}:{measurementName}”,
in which case the meaning of the parts SHOULD be as follows:</t>

<t><list style="symbols">
  <t>componentName: (optional) human-readable name for the component. MUST not
contain a colon, in the name, since colon is used as a separator.</t>
  <t>measurementName: (optional) name of the measurement type (a data point type)
that the status is reported for. MUST not contain a colon, in the name, since
colon is used as a separator. The observation’s name can be one of:
  <list style="symbols">
      <t>A pre-defined value from this spec. Pre-defined values include:
      <list style="symbols">
          <t>utilization</t>
          <t>responseTime</t>
          <t>connections</t>
          <t>uptime</t>
        </list></t>
      <t>A common and standard term from a well-known source such as schema.org, IANA
or microformats.</t>
      <t>A URI that indicates extra semantics and processing rules that MAY be
provided by a resource at the other end of the URI. URIs do not have to be
dereferenceable, however. They are just a namespace, and the meaning of a
namespace CAN be provided by any convenient means (e.g. publishing an RFC,
Open API Spec document or a nicely printed book).</t>
    </list></t>
</list></t>

<t>On the value side of the equation, each “component details” object in the array
SHOULD have at least one key, and MAY have any or none of the following object
keys:</t>

<section anchor="componentid" title="componentId">

<t>componentId: (optional) is a unique identifier of an instance of a specific
sub-component/dependency of a service. Multiple objects with the same
componentID MAY appear in the details, if they are from different nodes.</t>

</section>
<section anchor="componenttype" title="componentType">

<t>componentType: (optional) SHOULD be present if componentName is present. It’s
a type of the component and could be one of:</t>

<t><list style="symbols">
  <t>Pre-defined value from this spec. Pre-defined values include:
  <list style="symbols">
      <t>component</t>
      <t>datastore</t>
      <t>system</t>
    </list></t>
  <t>A common and standard term from a well-known source such as schema.org, IANA
or microformats.</t>
  <t>A URI that indicates extra semantics and processing rules that MAY be
provided by a resource at the other end of the URI. URIs do not have to be
dereferenceable, however. They are just a namespace, and the meaning of a
namespace CAN be provided by any convenient means (e.g. publishing an RFC,
Swagger document or a nicely printed book).</t>
</list></t>

</section>
<section anchor="observedvalue" title="observedValue">

<t>observedValue: (optional) could be any valid JSON value, such as: string, number,
object, array or literal.</t>

</section>
<section anchor="observedunit" title="observedUnit">

<t>observedUnit (optional) SHOULD be present if observedValue is present. Clarifies
the unit of measurement in which observedUnit is reported, e.g. for a time-based
value it is important to know whether the time is reported in seconds, minutes,
hours or something else. To make sure unit is denoted by a well-understood name
or an abbreviation, it SHOULD be one of:</t>

<t><list style="symbols">
  <t>A common and standard term from a well-known source such as schema.org, IANA,
microformats, or a standards document such as <xref target="RFC3339"/>.</t>
  <t>A URI that indicates extra semantics and processing rules that MAY be
provided by a resource at the other end of the URI. URIs do not have to be
dereferenceable, however. They are just a namespace, and the meaning of a
namespace CAN be provided by any convenient means (e.g. publishing an RFC,
Swagger document or a nicely printed book).</t>
</list></t>

</section>
<section anchor="status-1" title="status">

<t>status (optional) has the exact same meaning as the top-level “output”
element, but for the sub-component/downstream dependency represented
by the details object.</t>

</section>
<section anchor="affectedendpoints" title="affectedEndpoints">

<t>affectedEndpoints (optional) is a JSON array containing URI Templates as defined
by <xref target="RFC6570"/>. This field SHOULD be omitted if the “status” field is present
and has value equal to “pass”. A typical API has many URI endpoints. Most of the
time we are interested in the overall health of the API, without diving into
details. That said, sometimes operational and resilience middleware needs to
know more details about the health of the API (which is why “checks” property
provides details). In such cases, we often need to indicate which particular
endpoints are affected by a particular check’s troubles vs. other endpoints that
may be fine.</t>

</section>
<section anchor="time" title="time">

<t>time (optional) is the date-time, in ISO8601 format, at which the reading of the
observedValue was recorded. This assumes that the value can be cached and the
reading typically doesn’t happen in real time, for performance and scalability
purposes.</t>

</section>
<section anchor="output-1" title="output">

<t>output (optional) has the exact same meaning as the top-level “output” element,
but for the sub-component/downstream dependency represented by the details
object. As is the case for the top-level element, this field SHOULD be omitted
for “pass” state of a downstream dependency.</t>

</section>
<section anchor="links-1" title="links">

<t>links (optional) has the exact same meaning as the top-level “output”
element, but for the sub-component/downstream dependency represented
by the details object.</t>

</section>
<section anchor="additional-keys" title="Additional Keys">

<t>In addition to the above keys, additional user-defined keys MAY be
included in the ‘component details’ object. Implementations MAY ignore
any keys that are not part of the list of standard keys above.</t>

</section>
</section>
<section anchor="example-output" title="Example Output">

<figure><artwork><![CDATA[
  GET /health HTTP/1.1
  Host: example.org
  Accept: application/health+json

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

{
  "status": "pass",
  "version": "1",
  "releaseId": "1.2.2",
  "notes": [""],
  "output": "",
  "serviceId": "f03e522f-1f44-4062-9b55-9587f91c9c41",
  "description": "health of authz service",
  "checks": {
    "cassandra:responseTime": [
      {
        "componentId": "dfd6cf2b-1b6e-4412-a0b8-f6f7797a60d2",
        "componentType": "datastore",
        "observedValue": 250,
        "observedUnit": "ms",
        "status": "pass",
        "affectedEndpoints" : [
          "/users/{userId}",
          "/customers/{customerId}/status",
          "/shopping/{anything}"
        ],
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      }
    ],
    "cassandra:connections": [
      {
        "componentId": "dfd6cf2b-1b6e-4412-a0b8-f6f7797a60d2",
        "componentType": "datastore",
        "observedValue": 75,
        "status": "warn",
        "time": "2018-01-17T03:36:48Z",
        "output": "",
        "links": {
          "self": "http://api.example.com/dbnode/dfd6cf2b/health"
        }
      }
    ],
    "uptime": [
      {
        "componentType": "system",
        "observedValue": 1209600.245,
        "observedUnit": "s",
        "status": "pass",
        "time": "2018-01-17T03:36:48Z"
      }
    ],
    "cpu:utilization": [
      {
        "componentId": "6fd416e0-8920-410f-9c7b-c479000f7227",
        "node": 1,
        "componentType": "system",
        "observedValue": 85,
        "observedUnit": "percent",
        "status": "warn",
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      },
      {
        "componentId": "6fd416e0-8920-410f-9c7b-c479000f7227",
        "node": 2,
        "componentType": "system",
        "observedValue": 85,
        "observedUnit": "percent",
        "status": "warn",
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      }
    ],
    "memory:utilization": [
      {
        "componentId": "6fd416e0-8920-410f-9c7b-c479000f7227",
        "node": 1,
        "componentType": "system",
        "observedValue": 8.5,
        "observedUnit": "GiB",
        "status": "warn",
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      },
      {
        "componentId": "6fd416e0-8920-410f-9c7b-c479000f7227",
        "node": 2,
        "componentType": "system",
        "observedValue": 5500,
        "observedUnit": "MiB",
        "status": "pass",
        "time": "2018-01-17T03:36:48Z",
        "output": ""
      }
    ]
  },
  "links": {
    "about": "http://api.example.com/about/authz",
    "http://api.x.io/rel/thresholds":
      "http://api.x.io/about/authz/thresholds"
  }
}
]]></artwork></figure>

</section>
<section anchor="security-considerations" title="Security Considerations">

<t>Clients need to exercise care when reporting health information. Malicious
actors could use this information for orchestrating attacks. In some cases, the
health check endpoints may need to be authenticated and institute role-based
access control.</t>

</section>
<section anchor="iana-considerations" title="IANA Considerations">

<t>The media type for health check response is application/health+json.</t>

<t><list style="symbols">
  <t>Media type name: application</t>
  <t>Media subtype name: health+json</t>
  <t>Required parameters: n/a</t>
  <t>Optional parameters: n/a</t>
  <t>Encoding considerations: binary</t>
  <t>Security considerations: Health+JSON shares security issues common to all JSON
  content types. See RFC 8259 Section #12 for additional information.  <vspace blankLines='1'/>
Health+JSON allows utilization of Uniform Resource Identifiers (URIs) and as such
  shares security issues common to URI usage. See RFC 3986 Section #7
  for additional information.  <vspace blankLines='1'/>
Since health+json can carry wide variety of data, some data may require privacy
  or integrity services. This specification does not prescribe any specific
  solution and assumes that concrete implementations will utilize common, trusted
  approaches such as TLS/HTTPS, OAuth2 etc.</t>
  <t>Interoperability considerations: None</t>
  <t>Published specification: this RFC draft</t>
  <t>Applications which use this media: Various</t>
  <t>Fragment identifier considerations: Health+JSON follows RFC6901 for
implementing URI Fragment Identification standard to JSON content types.</t>
  <t>Restrictions on usage: None</t>
  <t>Additional information:
  <list style="numbers">
      <t>Deprecated alias names for this type: n/a</t>
      <t>Magic number(s): n/a</t>
      <t>File extension(s): .json</t>
      <t>Macintosh file type code: TEXT</t>
      <t>Object Identifiers: n/a</t>
    </list></t>
  <t>General Comments:</t>
  <t>Person to contact for further information:
  <list style="numbers">
      <t>Name: Irakli Nadareishvili</t>
      <t>Email: irakli@gmail.com</t>
    </list></t>
  <t>Intended usage: Common</t>
  <t>Author/Change controller: Irakli Nadareishvili</t>
</list></t>

</section>
<section anchor="acknowledgements" title="Acknowledgements">

<t>Thanks to  Mike Amundsen, Erik Wilde, Justin Bachorik and Randall Randall for
their suggestions and feedback. And to Mark Nottingham for blueprint for
authoring RFCs easily.</t>

</section>
<section anchor="creating-and-serving-health-responses" title="Creating and Serving Health Responses">

<t>When making an health check endpoint available, there are a few things to keep
in mind:</t>

<t><list style="symbols">
  <t>A health response endpoint is best located at a memorable and commonly-used
URI, such as “health” because it will help self-discoverability by clients.</t>
  <t>Health check responses can be personalized. For example, you could advertise
different URIs, and/or different kinds of link relations, to afford different
clients access to additional health check information.</t>
  <t>Health check responses SHOULD be assigned a freshness lifetime (e.g.,
“Cache-Control: max-age=3600”) so that clients can determine how long they
could cache them, to avoid overly frequent fetching and unintended DDOS-ing of
the service. Any method of cache lifetime negotiation provided by HTTP spec is
acceptable (e.g. ETags are just fine).</t>
  <t>Custom link relation types, as well as the URIs for variables, SHOULD lead to
documentation for those constructs.</t>
</list></t>

</section>
<section anchor="consuming-health-check-responses" title="Consuming Health Check Responses">

<t>Clients might use health check responses in a variety of ways.</t>

<t>Note that the health check response is a “living” document; links from the
health check response MUST NOT be assumed to be valid beyond the freshness
lifetime of the health check response, as per HTTP’s caching model <xref target="RFC7234"/>.</t>

<t>As a result, clients ought to cache the health check response (as per
<xref target="RFC7234"/>), to avoid fetching it before every interaction (which would
otherwise be required).</t>

<t>Likewise, a client encountering a 404 (Not Found) on a link is encouraged to obtain
a fresh copy of the health check response, to assure that it is up-to-date.</t>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor="RFC2119" target='https://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor="RFC3986" target='https://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>



<reference  anchor="RFC8288" target='https://www.rfc-editor.org/info/rfc8288'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<date year='2017' month='October' />
<abstract><t>This specification defines a model for the relationships between resources on the Web (&quot;links&quot;) and the type of those relationships (&quot;link relation types&quot;).</t><t>It also defines the serialisation of such links in HTTP headers with the Link header field.</t></abstract>
</front>
<seriesInfo name='RFC' value='8288'/>
<seriesInfo name='DOI' value='10.17487/RFC8288'/>
</reference>



<reference  anchor="RFC7234" target='https://www.rfc-editor.org/info/rfc7234'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t></abstract>
</front>
<seriesInfo name='RFC' value='7234'/>
<seriesInfo name='DOI' value='10.17487/RFC7234'/>
</reference>



<reference  anchor="RFC8259" target='https://www.rfc-editor.org/info/rfc8259'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials='T.' surname='Bray' fullname='T. Bray' role='editor'><organization /></author>
<date year='2017' month='December' />
<abstract><t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.</t><t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract>
</front>
<seriesInfo name='STD' value='90'/>
<seriesInfo name='RFC' value='8259'/>
<seriesInfo name='DOI' value='10.17487/RFC8259'/>
</reference>



<reference  anchor="RFC6570" target='https://www.rfc-editor.org/info/rfc6570'>
<front>
<title>URI Template</title>
<author initials='J.' surname='Gregorio' fullname='J. Gregorio'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='M.' surname='Hadley' fullname='M. Hadley'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='D.' surname='Orchard' fullname='D. Orchard'><organization /></author>
<date year='2012' month='March' />
<abstract><t>A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet.   [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6570'/>
<seriesInfo name='DOI' value='10.17487/RFC6570'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor="RFC7230" target='https://www.rfc-editor.org/info/rfc7230'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the &quot;http&quot; and &quot;https&quot; Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract>
</front>
<seriesInfo name='RFC' value='7230'/>
<seriesInfo name='DOI' value='10.17487/RFC7230'/>
</reference>



<reference  anchor="RFC6838" target='https://www.rfc-editor.org/info/rfc6838'>
<front>
<title>Media Type Specifications and Registration Procedures</title>
<author initials='N.' surname='Freed' fullname='N. Freed'><organization /></author>
<author initials='J.' surname='Klensin' fullname='J. Klensin'><organization /></author>
<author initials='T.' surname='Hansen' fullname='T. Hansen'><organization /></author>
<date year='2013' month='January' />
<abstract><t>This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols.  This memo documents an Internet Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='13'/>
<seriesInfo name='RFC' value='6838'/>
<seriesInfo name='DOI' value='10.17487/RFC6838'/>
</reference>



<reference  anchor="RFC7231" target='https://www.rfc-editor.org/info/rfc7231'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.</t></abstract>
</front>
<seriesInfo name='RFC' value='7231'/>
<seriesInfo name='DOI' value='10.17487/RFC7231'/>
</reference>



<reference  anchor="RFC3339" target='https://www.rfc-editor.org/info/rfc3339'>
<front>
<title>Date and Time on the Internet: Timestamps</title>
<author initials='G.' surname='Klyne' fullname='G. Klyne'><organization /></author>
<author initials='C.' surname='Newman' fullname='C. Newman'><organization /></author>
<date year='2002' month='July' />
<abstract><t>This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.</t></abstract>
</front>
<seriesInfo name='RFC' value='3339'/>
<seriesInfo name='DOI' value='10.17487/RFC3339'/>
</reference>




    </references>



  </back>

<!-- ##markdown-source:
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
vwDpJAxim0gAAA==

-->

</rfc>