draft-inadarei-api-health-check-06.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.5.10 -->

<!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-06" 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="2021"/>

    <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 fullname='S. Bradner' initials='S.' surname='Bradner'><organization/></author>
<date month='March' year='1997'/>
<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 fullname='T. Berners-Lee' initials='T.' surname='Berners-Lee'><organization/></author>
<author fullname='R. Fielding' initials='R.' surname='Fielding'><organization/></author>
<author fullname='L. Masinter' initials='L.' surname='Masinter'><organization/></author>
<date month='January' year='2005'/>
<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 fullname='M. Nottingham' initials='M.' surname='Nottingham'><organization/></author>
<date month='October' year='2017'/>
<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 fullname='R. Fielding' initials='R.' role='editor' surname='Fielding'><organization/></author>
<author fullname='M. Nottingham' initials='M.' role='editor' surname='Nottingham'><organization/></author>
<author fullname='J. Reschke' initials='J.' role='editor' surname='Reschke'><organization/></author>
<date month='June' year='2014'/>
<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 fullname='T. Bray' initials='T.' role='editor' surname='Bray'><organization/></author>
<date month='December' year='2017'/>
<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 fullname='J. Gregorio' initials='J.' surname='Gregorio'><organization/></author>
<author fullname='R. Fielding' initials='R.' surname='Fielding'><organization/></author>
<author fullname='M. Hadley' initials='M.' surname='Hadley'><organization/></author>
<author fullname='M. Nottingham' initials='M.' surname='Nottingham'><organization/></author>
<author fullname='D. Orchard' initials='D.' surname='Orchard'><organization/></author>
<date month='March' year='2012'/>
<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 fullname='R. Fielding' initials='R.' role='editor' surname='Fielding'><organization/></author>
<author fullname='J. Reschke' initials='J.' role='editor' surname='Reschke'><organization/></author>
<date month='June' year='2014'/>
<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 fullname='N. Freed' initials='N.' surname='Freed'><organization/></author>
<author fullname='J. Klensin' initials='J.' surname='Klensin'><organization/></author>
<author fullname='T. Hansen' initials='T.' surname='Hansen'><organization/></author>
<date month='January' year='2013'/>
<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 fullname='R. Fielding' initials='R.' role='editor' surname='Fielding'><organization/></author>
<author fullname='J. Reschke' initials='J.' role='editor' surname='Reschke'><organization/></author>
<date month='June' year='2014'/>
<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 fullname='G. Klyne' initials='G.' surname='Klyne'><organization/></author>
<author fullname='C. Newman' initials='C.' surname='Newman'><organization/></author>
<date month='July' year='2002'/>
<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:
H4sIAOvIamEAA+1c63LbyJX+j6fo4vwY2yEpipZ84V5qFdsTKxlbs5acbDaV
SjWJpogRCDBoQDTjcioPsvtyeZL9vnO6AVCSNc5lt7K7mR9jEmx0nz6X71z6
tEajUVJnde5m5rWzeb0yL1ZucWXeOb8pC+/MN2W1trVZlpV5fXHxnTn57tQn
dj6v3PUsSctFYdd4N63ssh5lhU1t5bKR3WSjlUw3WnC60eRJktoaA6eT6WGy
wMfLstrNTFYsyyTJNtXM1FXj6+lk8nwyTTCJnZmfuMJVNk+2ZXV1WZXNZpZc
uR2+pTNzWtSuKlw9esmVk8TXtkh/Y/OywCI755NNNjO/qsvF0OB/WZG6oh4a
X1Z15ZYen3br8KGusgV+WpTrjQ0f1hiMn7Iizwr36ySxTb0qq1liRonBf1nh
QcDYvNXd+tV1lmfyizLjtLJXeXbHz1jLuXpmDg+PzDFYfXLtisbJT4usBjve
uq35JXarj8qmqMmk90VWu9Sc12CbN+XSnKwdiLYyyq1tloORsua/XPLbGFuQ
35oKTFjV9WZ2cLDdbsfLyvnVPG+quZcxSSHCza4d9mbeffNienj4PHx8/PzZ
E378Cp+Pp9Mn4fGz6bNn4ePT6eOj9ulxfO/J8dPJDCKFYPfnxvBJHPPscW+S
w7ji48eYJBmNRsbOwSpII0kuVpk3ULOGMjGbqtyUHkywxrvqOls4o2pmRM1M
FbV2eYfWjnXuoqzdb97yf3X5m3fOpq7ySfLoESgwr16eXpy9m5lN7ixmqdy6
vHamJg3eLeqsLMzcYVJnNs08hwj46NEjkulM5n0D0vLM68LymhiGWVi+iKdN
kRrQ9Y8UiodULrN61cwpjINoPAfVchGMRzZ1oPP+81hXWZeYvnILskMnxyr9
KeM84zB3Vt6akXO90ykWK1tckqHYEyl3fzp9NJis9gdri9crzn3unLG5L8EC
p0R+7c2iqSquCEutGw8jkl9PX118YwANlvK+ctUQyyft8r0fxpmrl+OyujyA
Nhz8AN7IDinsdZamuUuSrwgYVZk2IkTl5DXoNWv7fVnB9mhW6xK6UIiugOrs
OisuhTQgiNm6uQHCYMw8y7G7zSaK35vGu0S07OPHoOefPhnrub+sos4Cgcp8
bLhoUFdO1WzqbO24MAZC2wRZUwcergE7xl7DlC1WC9SRW3vL4sHau/za+TF2
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
8b0F7L9JvD3pTgdYpE4SmGA8Meja/dhbqwXK3mlCA8Vt84yrUOHWHpOuy43v
f30rW/060mBObzSNcYrssmAqQpiUabVziUAEX01jjigjDbz43EYzMrytKZtX
HyynN2dBcX//+9/Dh/7k1YUJnSRSoD44HB/KAZmvZxQOX2Gow3NnaXSYmc/0
oCThNJ4zmOlkYs5+hicvtCNlpPnh517FOJruiKOrMp/BLXwY2Uv3T4+fTCY6
Syj7zMwiL9l68xGPox+aBQfDoGAQTsj48FCfdEdsfDaejqf6XE7E8OxXg8Gv
5UHQM4zSAW3pnY+Wk8fueDpdjg6XR0ejo8mT6ej5/Ph49Pz42dPl88PF88VR
WK9XH+eLnTNgQ/7vYt6uY4MjmJmP2g0CC/WQX2Vn/eoXiZTfTRinY7tSA9dJ
l+mTxXI6Hx3On7jR0dHhdGQn82ej5ZPl06fPn9onk1Q3fvN1ykYmiIlvf9Qe
JGPU9Hhyx6/MIjjF2vffvUM84ZdbYczAdFuUEQe0KH/wkf+cpp96L/PHBUJO
OG4OiB8x6CAsuD/Wr8rNBsBy8BFGJJnGp0E74Nc9omrl9GA6OXw2mhyODp9e
TB7PHj+ZHT379z2WdGoSHn5KenP1ZNgrV/4NifDp8Z0ykvPav4wdvaeC+K1e
x8V4kEaT0MsddpONI8awVz+ds9J0ELkQIKIT1qc72a0V4B/gb2SQFnPu487h
dPIcqDOeHh3fo+hfqOf38vBu5dk0s14p/IvU5skyPTp84iajZ8+nk9HR4WQ5
er54Crd49PT5ZDJZPp1On/apIpe50/s06YcZ9ew+/iCQ4kWNu7n0V9C0yLvh
fxdzpv8HmLOnWGu35t21/yW6Nb6Pfz/Jfvz/VrGOjyf3OeA3n2PNn4RMX6JW
SWDSDaQfSBZ8D8jL7wcSCoV1+iM/yMUvlx/UK976K/MUU4eFb43rTdUfT8qS
TxLgIu49d4tGrkq94FF4GnJ8BPex+zDm0+4DzDJjawbD6+3KFaGE2esE6Hfo
mDcWwWxWNj5BDlNWPlSKGx/u3vX7Z5itlBWiPd4QlBltXVu28EmeL328NrYY
JHt3b7pcnGl4pJb1aGycB0mhmYV9vEW4YGEQRcfKLRuUvfaG46nkAixb3uLH
xX6v+c2rJ13rStdieTOQl8scb7o59GJpv/0k/oysrTeinws8Mu9CWznTG/xc
I8ybmeLA4qez2CF7+6dXxaJM9aZXf18zM88KW+0wotWEmyO0jf9HUjnzK0hf
+hl0bLgeGcrFbPfIc6mxiVLGhnvuBaLkDUJeyGQXP5cT0X91ONVy+p0twdLS
a/ZIkFtHvn8gzuThfbht8y5WdE/bU0Rk1qzgagu/1b5cmfUHN8PKW8PrUx3t
7BLraH8q8/wg+dpt0xOjlGRgSNXu1v02xqhad9MmB2p1uEnAmu21Xezi2Rgr
fpdCeUiaQiNhe0Sq3GFZR/PhKlyokFpye44qrAgX8AKPemUk9s/zDoi5eWdr
m0HUKgUXeDbU+95Oe/eh2FXJxNW3hf2Lb88PmAWfD83ZCexzaly9YC/I6c0r
YzeV8C0cAcZ9F65CpPt7nCmkUEByiRQjT/pX77Sk1kKP2PHM/BxcJz49Mt9U
9lIPgLqz5/vMILTVyLXn51q9w5ZbDsWScjttVMYgke5IpdSC9L6hiJHrFXah
Hm+IFrZcOLlT2dQRHI7NS9ZzAuzxzoWeK3R3l2qpNhAX+MKUUH2ZLcLJ3AP/
sPvt8dh8w5uxbIgsWDeQX8ehKmHMEd9dsHrsV2bJkQJb7N6bmYtX/3Yho47H
odWtb5QRmMLfAwDe6g39GaWM39UCpUa/0HLWsqmk+nrXlt/ef0cfe3z1mSv1
qnsFa1CByS9El8lm+QsBBy+00Tl4iNxVn1mI16AWrHvnLr3Um250G1ZaSEtj
3mRXzpysmyL1DqbyqsquzC+ynI2OP214S878GNZS8jGt8B11BCYW/6WOSbc3
rOnyktfqYg/rEk6PDXtjc1KITr2x1RWvnFERV1auIJo5AiQ585GJ9I8fUE+h
wt4467NcapLmBe99xjuO58QVfL5xtQv7+gUDgHB5GFh2p0s27QXfeK1WCu6g
d2uk0iB8uXJuw962dVak0qfW3uBoXWr/+sIcOzd5GdSbJ2sSuusNI+mEoPTy
3YhtWxA+G1hb/AnVpgFmWVjCQVYrjq1cvjHMv0fxjkEEoq5tlXb5+i6X72OF
fSN6a4mI4VZOCO2GZlc2IQCyKWavEUkl/U52eig5GTzAW91j8Fdvuuy3LksP
v11CkmnvVq1p76OGoIaDOqjYk9Gek/rsvvq9hOFygzXyBycKzp9nS6enHDyG
lHD3nkrl4KGRvx5Ap9K7N9tdjl+VW0hWb3rSySm/5NiCj9a6a2lEpoTyXXvl
ACpVL1ZRa5siiyb98uXZ+UiPUJK9Cxe0FV4JghnIYa+u0m6ocJdlrQfle4ew
esGJTVrSr9+73aYnsa8u7KXvjn1Z8H5I/r6QMty+FBXtpcuZx+mxsi+nzbRY
BgWcGkOCHHifgodrpj3S7cJnbET6pgu9WuOlRV6i2GbdM+H9y5i9OH/NG27i
Iu8Ma+U+l+0HKlu74yL8oxvdgdPnQ2JmQsSSQUv7P4T2+niJI7n75XgXNmgh
Xo0RvnabzN2uDAfqrWYmrSBD+f/OqYX1sFmRKv+Yhf6dA/mTEXl7xf5Irrie
eG0XaHL+NZnAs7Ihz+imoo5+hgEPdKGkN+fDnja32gs4Cn+KhE0EOz3TtRps
hjPSLY0ikXPILdOxuTPtRVPQ+S2cDJ+zJ1rJBHrKH51xlV5rPpocmQeQGvAJ
rughowvbdu/LWEQtyuNyzgPyJJg8lGuz+wGGckteelO0WUMgu9mM6nKUyr2V
/wLaaOkYm0gAAA==

-->

</rfc>