Skip to content

Commit

Permalink
feat(guidelines): add guidelines for test header usage in rest apis (#65
Browse files Browse the repository at this point in the history 
)
  • Loading branch information
@maxedenharter0507
maxedenharter0507 authored Sep 18, 2024
1 parent 15c925d commit f11b057
Show file tree
Hide file tree
Showing 3 changed files with 75 additions and 21 deletions.
43 changes: 22 additions & 21 deletions api-guidelines/rest/http/headers/list-of-headers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,29 @@ The list of headers is not supposed to be exhaustive, but contains the most comm
We do not prohibit the use of headers that are not listed below.
HTTP/1.1-related headers, for example, `Connection`, are not explicitly listed.

| Header Name | Description | Part of Request | Part of Response |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------: | :--------------: |
| `Accept` | Used for content negotiation, indicates which content types the client understands in a response. | ✔ | ✗ |
| `Accept-Encoding` | Used for content negotiation, a client advertises which content encoding algorithms it understands in a response. Possible values are `gzip`, `compress`, `deflate`, `identity`, and `br`. | ✔ | ✗ |
| `Allow` | Contains the set of methods supported by a resource. This header must be set when responding with `405 Method Not Allowed`. Example: `Allow: GET, PUT, HEAD`. | ✗ | ✔ |
| `Authorization` | Includes the credentials for accessing a given resource. Refer to [MUST use Bearer Authentication](../../authorization/oauth/rules/must-use-bearer-authentication.md). | ✔ | ✗ |
| `Content-Encoding` | Indicates the content encoding used for the response body. Refer to `Accept-Encoding`. | ✗ | ✔ |
| `Content-Length` | The size of the request payload or response body in bytes. | ✔ | ✔ |
| `Content-Type` | Indicates the media type of a resource. Describes the payload format of requests and the content type of responses. Required for `PUT` and `POST` requests. | ✔ | ✔ |
| `Date` | Contains the timestamp of the request (client) and response (server) respectively. The timestamp format must follow [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1) | ✔ | ✔ |
| `ETag` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✗ | ✔ |
| Header Name | Description | Part of Request | Part of Response |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :-------------: | :--------------: |
| `Accept` | Used for content negotiation, indicates which content types the client understands in a response. | ✔ | ✗ |
| `Accept-Encoding` | Used for content negotiation, a client advertises which content encoding algorithms it understands in a response. Possible values are `gzip`, `compress`, `deflate`, `identity`, and `br`. | ✔ | ✗ |
| `Allow` | Contains the set of methods supported by a resource. This header must be set when responding with `405 Method Not Allowed`. Example: `Allow: GET, PUT, HEAD`. | ✗ | ✔ |
| `Authorization` | Includes the credentials for accessing a given resource. Refer to [MUST use Bearer Authentication](../../authorization/oauth/rules/must-use-bearer-authentication.md). | ✔ | ✗ |
| `Content-Encoding` | Indicates the content encoding used for the response body. Refer to `Accept-Encoding`. | ✗ | ✔ |
| `Content-Length` | The size of the request payload or response body in bytes. | ✔ | ✔ |
| `Content-Type` | Indicates the media type of a resource. Describes the payload format of requests and the content type of responses. Required for `PUT` and `POST` requests. | ✔ | ✔ |
| `Date` | Contains the timestamp of the request (client) and response (server) respectively. The timestamp format must follow [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1) | ✔ | ✔ |
| `ETag` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✗ | ✔ |
| `Forwarded` | Contains information from the client side of proxy servers that is altered or lost when a proxy is involved. This can be the original `Host` requested by a client, for example to [generate absolute URLs in links](../../hypermedia/links/rules/must-use-absolute-urls.md). Refer to [RFC 7239](https://tools.ietf.org/html/rfc7239). | ✔ | ✗ |
| `Host` | Contains the hostname (and non-default port) of the client's request. Example: `Host: api.otto.de` | ✔ | ✗ |
| `If-Match` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✔ | ✗ |
| `If-None-Match` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✔ | ✗ |
| `Location` | Contains the redirect URL. This URL must be fully qualified. | ✗ | ✔ |
| `Retry-After` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `Server` | The header describes the software used by the server that handled the request. | ✗ | ✔ |
| `User-Agent` | Used by a client to identify itself to the server. It should include a unique, human-readable identifier, optionally suffixed by a version string reflecting different software releases of the client. Example: `User-Agent: otto-ready/v2.3.1` | ✔ | ✗ |
| `X-RateLimit-Limit` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `X-RateLimit-Remaining` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `X-RateLimit-Reset` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `Host` | Contains the hostname (and non-default port) of the client's request. Example: `Host: api.otto.de` | ✔ | ✗ |
| `If-Match` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✔ | ✗ |
| `If-None-Match` | Used for [caching](./rules/may-use-etag-header-for-caching-resources.md) and [concurrency control](./rules/should-use-etag-together-with-if-match-if-none-match-header-for-concurrrency-control.md). | ✔ | ✗ |
| `Location` | Contains the redirect URL. This URL must be fully qualified. | ✗ | ✔ |
| `Retry-After` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `Server` | The header describes the software used by the server that handled the request. | ✗ | ✔ |
| `Test` | Used to indicate that a request or response is part of a test. Refer to [MAY use `Test` header](./rules/may-use-test-header.md). | ✔ | ✔ |
| `User-Agent` | Used by a client to identify itself to the server. It should include a unique, human-readable identifier, optionally suffixed by a version string reflecting different software releases of the client. Example: `User-Agent: otto-ready/v2.3.1` | ✔ | ✗ |
| `X-RateLimit-Limit` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `X-RateLimit-Remaining` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |
| `X-RateLimit-Reset` | Used for rate limiting. Refer to [MUST use code 429 with headers for rate limits](../status-codes/rules/must-use-code-429-with-headers-for-rate-limits.md). | ✗ | ✔ |

::: references

Expand Down
Loading

0 comments on commit f11b057

Please sign in to comment.