draft-inadarei-api-health-check-03.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.9 -->

<!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-03" 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</country>
        </postal>
        <email>irakli@gmail.com</email>
        <uri>http://www.freshblurbs.com</uri>
      </address>
    </author>

    <date year="2019"/>

    <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 array of objects containing link relations and URIs
<xref target="RFC3986"/> for external links that MAY contain more information about the
health of the endpoint. 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,
Swagger 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
MAY have one 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>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. The <spanx style="verb">affectedEndpoints</spanx>
property is a JSON array containing URI Templates as defined by <xref target="RFC6570"/>.</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.</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>
<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",
        "type": "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:
H4sIAN2FoVwAA+1c23LbypV9x1d00Q+xHZK62zLnUqPIOrEyx9YZS04mk0ol
TaAp4ggEGDQgmnE5lQ+Z+bl8yay1dzcISvIlmWQqk8l5OCaJRvfufVn70rs1
Go2SJm8KNzGvnC2auTmdu/TGvHV+WZXemW+qemEbM6tq8+rq6jtz8t25T+x0
WrvbSZJVaWkXeDer7awZ5aXNbO3ykV3mo7lMN0o53Wj3IMlsg4H7u3vHSYqP
11W9npi8nFVJki/riWnq1jf7u7svdvcTTGIn5seudLUtklVV31zXVbucJDdu
jW/ZxJyXjatL14xecuUk8Y0ts1/ZoiqxyNr5ZJlPzC+aKh0a/C8vM1c2Q+Or
uqndzOPTehE+NHWe4lFaLZY2fFhgMB7lZZGX7pdJYttmXtWTxIwSg//y0oOA
sXmju/Xz27zI5Yky47y2N0X+wGOs5VwzMXt7h+YIrD65dWXr5FGaN2DHG7cy
P8du9aeqLRsy6V2ZNy4zlw3Y5uWRW9i8APdkoX+55rcx6JZnbY2dz5tmOdnZ
Wa1W41nt/HxatPXUy5ikFInmtw4bMm+/Od3f23sRPh68OH7Gj4/w+Wh//1n4
+Xj/+Dh8fL5/cNj9ehTfe3b0fHcCOUKa23Nj+G4cc3zQm2QvrnhwgEmS0Whk
7BT8gQiS5GqeewPdaikIs6yrZeWdN9Z4V9/mqTOqW0Z0y9RRVWcPqOpY5y6r
xv3qDf/XVL9662zmap8kT5+CAnP28vzq4u3ELAtnMUvtFtWtMw1p8C5t8qo0
U4dJnVm20yKH8uKnp09JpjO59y1IK3KvC8trYg0mtXwRv7ZlZkDXP1IoHlK5
zpt5O6UwdqLF7NSzNFiMbGpH5/3nsa6yqDB97VKyQyfHKv0p4zzjMHde3ZuR
c73VKdK5La/JUOyJlLs/nj5aSd74nYXF6zXnvnTO2MJXYIFTIn/gTdrWNVeE
eTath+XI0/Ozq28M8MBS3jeuHmL5pFu+92Ccu2Y2rurrHWjDzhdARnZIYS/y
LCtckjwiStRV1ooQlZO3oNcs7PdVDYMz1QyshS6UoiugOr/Ny2shDbBhVm5q
ACsYM80L7G65jOL3pvUuES378CHo+cePxnruL6+ps4CdqhgbLhrUlVO1yyZf
OC6MgdA2gdPMgYcLYI2xtzBli9UCdeTW1rL4YeFdcev8GLszWU78mrYUoV9D
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
+plBOBbhj3v6y+Zchb+N98f7+rscg+C3XwwGv5QfgiQwSgd0VVr+NNs9cEf7
+7PR3uzwcHS4+2x/9GJ6dDR6cXT8fPZiL32RHob1eqVUvrgBazZf/zZmhDo2
AOPEfNAeAICfh43UdtKvk5BIeW7COB27SWK5TjbLnqWz/elob/rMjQ4P9/ZH
dnd6PJo9mz1//uK5fbab6cbvvk7ZyAQxpeqP2kIPjNo/2n3gKQNTTrHw/Xcf
EE94cg9OB2azRRmx02Jmv/OB/5xnH3sv82GKKAaOjAPiRwzaCQtuj/XzarmE
6e18gO+V4PXjoBvwyx5RjXJ6wMb+0e7eaO/51e7B5ODZ5PD4P7ZYslGT8OPH
pDdXT4a9wtZfRITNHyO550cPikbO5v5nXOj9KlDYqXNcjEcttARt5bfLfByh
hZ3Z2ZSli524+YAMGxl9fJDLWiL8Alujamt14HPc2dvffQGwGe8fHn1Gv79S
vT/Lw4d1ZtlOerXSr9KWZ7PscO+Z2x0dv9jfHR3u7c5GL9Ln8BeHz1/s7u7O
nu/vP+9TRS5zp5/DgC8z6vhz/IGrZ1v+w1z6M2ha5N3wL8Wc/b8B5mwp1sIt
eD3p/4hujT/Hvx/nP/p/q1hHR7uf87uvP8WaPwqZvkatksCkO0g/kGTwMyAv
z3ckAgrr9Ee+l2s+rthp5rzjVRUZpg4L3xvXm6o/npQlHyWuRbh76dJWLsac
8rA0C6kugvXYahbTSvceZpnz8J7J42ruylAM650V97sxzGuLGDavWp8guK9q
H2qOrQ83rfodEgzjqxpBHu+DyYy2aSz7tSTdlaZNGw+hk62bFpuUlNlopJaV
TWycJxOh3YFNm2VopzcInmMNkN2oXvtA8KukACyA3ePH1XZn8d2LBpvmhk0/
3d34XVr3X2/m0LuD/QaF+BjpTG9EPwV4at6GHmKm7HjcILqbmHLH4tFFbIe8
/+isTKtM7/X09zUx07y09RojOk24O0Kbtn8ombufQ/py4q1jw2W4UHhkQ0BR
SI4vShnbq7kXiJL3xXj9jj3bXE5E/2hvXwuzD/Z/Sv+m2SJB7pj4/okpc4Z3
4W7F21gbPO+OpZByshaoDdtWmzBl1i9uhmWJlpdlNrSzD2hD+3OZ54vkaz9G
T4xSNIAh1et7t5kYo2r5SU/BqdWhbZzVv1ubruNhCwtf10J5yJVC01h35qbc
YeFBqqBMf6V9XqqS3cGcsCJctwo86hU62CzNjn9z94bOKoeoVQou8GyoV3qd
NmpDseuK+arvSsRX317uMPm9HJqLE9jnvnFNymaB87sXhO4q4Rs4Aoz7LvS9
Z9t7nCikUEByZRAjT/oXrbTo00GP2PHE/BRcJz49Nd/U9lqPEjaHmZ8zg9B4
IZdcX2h9acMfWFlCzekmjaoY5LEpzVdaDts2EzFxvaMstOMN0cGOBycPqpq6
gb2xeckyRwA9ttdrfXpzT6WREgNRgS/sE6iv8zSc8Dz2TzbPDsbmG96CZMNb
yWKBPB2HUoQxh3w3ZQnVz82MIwW02N01MVdn/34lo47GoRWqb5IRlsKFb6Ct
XsGeUMZ4rvYnFcJUqzyztpYS5ENbfvP5S9jY49knrk+r5pUs1gcmn4omk81y
BXznVFtag38oXP2JhXjlJWXxt3DZtd5qotOw0iJYGfM6v3HmZNGWmXcwlLM6
vzE/yws2wv2k5Y0o8yPYSsWfaYNvqSMwsPgv+5mkrxe2dH3NK1SxR3EGl8eG
rrE5KUWnXtv6hteLqIhzK9fNzBThkZwdyER6u53eAArsjbM+L9bi+k55xy/e
Z7skquDznWs82NfP6P7DRVEg2YMO2XSXOeMVSqk6g96VkfKClsudW7L3aZGX
mfQxdc36nUPtd6pPsXNTVEG9eUIjgbteJpGDdUqvWI/Y1QPhs8GxQ59QYhpg
ltQSDPJGUWzuiqVh9j2K7eQRhjZtjbTLVw85fB8rwEvRW0s8DBcwQmA3NOuq
DeGPzTB7gzgq6fcs0z/JCdMO3tr8DP7qpYbt1lTp1rYzSDLr3aA03d3DENJw
0AYqtmS05aI+ua9+r1loY7dG/rhAyfmLfOa0Cs/jLAl2P1OeHDwxclOcLqV3
R3JzEXperSBZvdVHF6f8krK63IHWXUujKiVUrLvmcqhUk86j1rZlHk365cuL
y5GW+JOt1nraCm9/wAzk0FBX6TZUuuuq0QPXrcM8vcsCx6M9572LTHqid3Zl
r/3m+JBHGE/I31OpvW1LUdFeumB5LBsL3nJqSYtlSMCpeddB7wGwcx48oOKE
o8FN8IyNSF9tqbcovDRDSwzbLnomvH3xrhflL3iZSRzkg0GtXN2x/TBlZddc
hH9gYXMg8umAmHkQsWTQ0f4PoX06tusnD78c7z0GLcSrMb7XroWpW1fhYLbT
zKQTZDhpe3BqYT1sVqTKP1ygd9rlzwMU3XXqQzl1OvF67NwW/HMhgWdVS57R
TUUd/QQDHutCSW/OJz1t7rQXcBT+7AQPo9d6sGk11AwHhStqQiKHcSsmY1Nn
ujuFoPNbOBn+zp5ZJRPoKX9VxNV6hfVw99A8htSAT3BFTxhd2K67W8YialEe
V1MezyXB5KFcy/UXGMoteelx0EN/gex2OWqqUSY3FP4b8L02BHxGAAA=

-->

</rfc>