Skip to content

Consistently use HTTP "header field" vocabulary #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Consistently use HTTP "header field" vocabulary #25

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions draft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,19 +92,19 @@ For a resource, deprecation could involve one or more parts of request, response

* URI - deprecation of one ore more query parameter(s) or path element(s)
* method - HTTP method for the resource is deprecated
* request header - one or more HTTP request header(s) is deprecated
* response header - HTTP response header(s) is deprecated
* request header - one or more HTTP request header field(s) is deprecated
* response header - HTTP response header field(s) is deprecated
* request body - request body contains one or more deprecated element(s)
* response body - response body contains one or more deprecated element(s)

The purpose of the `Deprecation` header is to provide just enough "hints" about the deprecation to the client application developer. It is safe to assume that on reception of the `Deprecation` header, the client developer would look up the resource's documentation in order to find deprecation related semantics. The resource developer could provide a link to the resource documentation using a `Link` header with relation type `deprecation` as shown below.
The purpose of the `Deprecation` header field is to provide just enough "hints" about the deprecation to the client application developer. It is safe to assume that on reception of the `Deprecation` header field, the client developer would look up the resource's documentation in order to find deprecation related semantics. The resource developer could provide a link to the resource documentation using a `Link` header field with relation type `deprecation` as shown below.

Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html"

In this example the interlinked content provides additional information about the deprecation of the resource context. There is no Deprecation header field in the response, and thus the resource is not deprecated. However, the resource already exposes a link where information is available how deprecation is managed for the context. This may be documentation explaining the use of the Deprecation header field, and also explaining under which circumstances and with which policies (announcement before deprecation; continued operation after deprecation) deprecation might be happening.

The following example uses the same link header, but also announces a deprecation date using a Deprecation header field.
The following example uses the same link header field, but also announces a deprecation date using a Deprecation header field.

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://developer.example.com/deprecation>;
Expand Down Expand Up @@ -135,7 +135,7 @@ This example provides link to an alternate resource to the requested resource th
# Sunset


In addition to the deprecation related information, if the resource provider wants to convey to the client application that the deprecated resource is expected to become unresponsive at a specific point in time, the Sunset HTTP header field {{?RFC8594}} can be used in addition to the `Deprecation` header.
In addition to the deprecation related information, if the resource provider wants to convey to the client application that the deprecated resource is expected to become unresponsive at a specific point in time, the Sunset HTTP header field {{?RFC8594}} can be used in addition to the `Deprecation` header field.

The timestamp given in the `Sunset` header field MUST be the later or the same as the one given in the `Deprecation` header field.

Expand Down Expand Up @@ -205,17 +205,17 @@ This is a list of implementations that implement the deprecation header field:

Organization: Apollo

- Description: Deprecation header is returned when deprecated functionality (as declared in the GraphQL schema) is accessed
- Description: Deprecation header field is returned when deprecated functionality (as declared in the GraphQL schema) is accessed
- Reference: https://www.npmjs.com/package/apollo-server-tools

Organization: Zalando

- Description: Deprecation header is recommended as the preferred way to communicate API deprecation in Zalando API designs.
- Description: Deprecation header field is recommended as the preferred way to communicate API deprecation in Zalando API designs.
- Reference: https://opensource.zalando.com/restful-api-guidelines/#deprecation

Organization: Palantir Technologies

- Description: Deprecation header is incorporated in code generated by conjure-java, a CLI to generate Java POJOs and interfaces from Conjure API definitions
- Description: Deprecation header field is incorporated in code generated by conjure-java, a CLI to generate Java POJOs and interfaces from Conjure API definitions
- Reference: https://github.com/palantir/conjure-java

Organization: IETF Internet Draft, Registration Protocols Extensions
Expand All @@ -225,17 +225,17 @@ Organization: IETF Internet Draft, Registration Protocols Extensions

Organization: E-Voyageurs Technologies

* Description: Deprecation header is incorporated in Hesperides, a configuration management tool providing universal text file templating and properties editing through a REST API or a webapp.
* Description: Deprecation header field is incorporated in Hesperides, a configuration management tool providing universal text file templating and properties editing through a REST API or a webapp.
* Reference: https://github.com/voyages-sncf-technologies/hesperides/blob/master/documentation/lightweight-architecture-decision-records/deprecated_endpoints.md

Organization: Open-Xchange

* Description: Deprecation header is used in Open-Xchange appsuite-middleware
* Description: Deprecation header field is used in Open-Xchange appsuite-middleware
* Reference: https://github.com/open-xchange/appsuite-middleware

Organization: MediaWiki

* Description: Core REST API of MediaWiki would use Deprecation header for endpoints that have been deprecated because a new endpoint provides the same or better functionality.
* Description: Core REST API of MediaWiki would use Deprecation header field for endpoints that have been deprecated because a new endpoint provides the same or better functionality.
* Reference: https://phabricator.wikimedia.org/T232485


Expand All @@ -246,27 +246,27 @@ This is a list of implementations that implement the general concept, but do so

Organization: Zapier

- Description: Zapier uses two custom HTTP headers named `X-API-Deprecation-Date` and `X-API-Deprecation-Info`
- Description: Zapier uses two custom HTTP header fields named `X-API-Deprecation-Date` and `X-API-Deprecation-Info`
- Reference: https://zapier.com/engineering/api-geriatrics/

Organization: IBM

- Description: IBM uses a custom HTTP header named `Deprecated`
- Description: IBM uses a custom HTTP header field named `Deprecated`
- Reference: https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/com.ibm.qradar.doc/c_rest_api_getting_started.html

Organization: Ultipro

- Description: Ultipro uses the HTTP `Warning` header as described in Section 5.5 of {{!RFC7234}} with code `299`
- Description: Ultipro uses the HTTP `Warning` header field as described in Section 5.5 of {{!RFC7234}} with code `299`
- Reference: https://connect.ultipro.com/api-deprecation

Organization: Clearbit

- Description: Clearbit uses a custom HTTP header named `X-API-Warn`
- Description: Clearbit uses a custom HTTP header field named `X-API-Warn`
- Reference: https://blog.clearbit.com/dealing-with-deprecation/

Organization: PayPal

- Description: PayPal uses a custom HTTP header named `PayPal-Deprecated`
- Description: PayPal uses a custom HTTP header field named `PayPal-Deprecated`
- Reference: https://github.com/paypal/api-standards/blob/master/api-style-guide.md#runtime


Expand All @@ -276,11 +276,11 @@ The Deprecation header field SHOULD be treated as a hint, meaning that the resou

In cases, where the Deprecation header field value is a date in future, it can lead to information that otherwise might not be available. Therefore, applications consuming the resource SHOULD verify the resource documentation and if possible, consult the resource developer to discuss potential impact due to deprecation and plan for possible transition to recommended resource.

In cases where `Link` header is used to provide more documentation and/or recommendation for replacement, one should assume that the content of the `Link` header field may not be secure, private or integrity-guaranteed, and due caution should be exercised when using it. Applications consuming the resource SHOULD check the referred resource documentation to verify authenticity and accuracy.
In cases where `Link` header field is used to provide more documentation and/or recommendation for replacement, one should assume that the content of the `Link` header field may not be secure, private or integrity-guaranteed, and due caution should be exercised when using it. Applications consuming the resource SHOULD check the referred resource documentation to verify authenticity and accuracy.

The suggested `Link` header fields make extensive use of IRIs and URIs. See {{!RFC3987}} for security considerations relating to IRIs. See {{!RFC3986}} for security considerations relating to URIs. See {{!RFC7230}} for security considerations relating to HTTP headers.

Applications that take advantage of typed links should consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from the HTTP headers. In particular, Link headers that use the `successor-version`, `latest-version` or `alternate` relation types should be treated with due caution. See {{?RFC5829}} for security considerations relating to these link relation types.
Applications that take advantage of typed links should consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from the HTTP headers. In particular, Link header fields that use the `successor-version`, `latest-version` or `alternate` relation types should be treated with due caution. See {{?RFC5829}} for security considerations relating to these link relation types.



Expand All @@ -290,7 +290,7 @@ The first example shows a deprecation header field without date information:

Deprecation: true

The second example shows a deprecation header with date information and a link to the successor version:
The second example shows a deprecation header field with date information and a link to the successor version:

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version"
Expand Down