diff --git a/api-guidelines/global/compatibility/deprecation/rules/must-not-start-using-deprecated-apis.md b/api-guidelines/global/compatibility/deprecation/rules/must-not-start-using-deprecated-apis.md deleted file mode 100644 index 68a15a1d..00000000 --- a/api-guidelines/global/compatibility/deprecation/rules/must-not-start-using-deprecated-apis.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: R000071 ---- - -# MUST NOT start using deprecated APIs - -Consumers must not start using deprecated APIs, API versions or API features. diff --git a/api-guidelines/global/compatibility/preview/README.md b/api-guidelines/global/compatibility/preview/README.md deleted file mode 100644 index 7ee9428c..00000000 --- a/api-guidelines/global/compatibility/preview/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Preview of API changes - -One of the main consequences of [contract first](../../core-principles/contract-first.md) is that agreed API specifications are published that are not yet or not fully implemented. -To make this transparent for all API consumers, there must be the possibility to mark corresponding parts in the API specification as such. - -[Rules](./rules) diff --git a/api-guidelines/global/compatibility/preview/rules/must-not-rely-on-preview.md b/api-guidelines/global/compatibility/preview/rules/must-not-rely-on-preview.md deleted file mode 100644 index ab0ae51b..00000000 --- a/api-guidelines/global/compatibility/preview/rules/must-not-rely-on-preview.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: R000077 ---- - -# MUST NOT rely on API components marked as preview - -API specification components marked as preview are intended to inform API consumers about upcoming changes or additions. Details of both the specification and implementation are subject to change and, in case of doubt, will not be used productively, so a productive application should not rely on their availability and reliability. If an API consumer relies on appropriately marked API components, they must check with the API provider to find out when these changes will take effect, and only then can they go live with their own updated API client. diff --git a/api-guidelines/rest/compatibility/client-behavior/rules/must-accept-undocumented-status-codes.md b/api-guidelines/rest/compatibility/client-behavior/rules/must-accept-undocumented-status-codes.md deleted file mode 100644 index 4983597f..00000000 --- a/api-guidelines/rest/compatibility/client-behavior/rules/must-accept-undocumented-status-codes.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: R000080 ---- - -# MUST accept undocumented status codes - -Clients must be prepared to handle HTTP status codes not explicitly specified in endpoint definitions. - -Clients are not required to understand every status code returned, but they must at least understand the class of each status code (i.e. 1xx, 2xx, 3xx, 4xx, 5xx) as defined in [RFC 7231 Section 6](https://tools.ietf.org/html/rfc7231#section-6). Clients must treat an unrecognized status code equivalent to the x00 status code (i.e. 100, 200, 300, 400, 500) of its class. diff --git a/api-guidelines/rest/compatibility/client-behavior/rules/must-follow-redirection.md b/api-guidelines/rest/compatibility/client-behavior/rules/must-follow-redirection.md deleted file mode 100644 index d42b927f..00000000 --- a/api-guidelines/rest/compatibility/client-behavior/rules/must-follow-redirection.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: R000081 ---- - -# MUST follow redirection - -Clients must follow the redirect when the server returns the HTTP status code `HTTP 301 Moved Permanently`. This allows services to evolve without breaking compatibility. diff --git a/api-guidelines/rest/compatibility/deprecation-of-http-apis/rules/should-add-deprecation-and-sunset-header-to-responses.md b/api-guidelines/rest/compatibility/deprecation-of-http-apis/rules/should-add-deprecation-and-sunset-header-to-responses.md index c19aa397..c657926f 100644 --- a/api-guidelines/rest/compatibility/deprecation-of-http-apis/rules/should-add-deprecation-and-sunset-header-to-responses.md +++ b/api-guidelines/rest/compatibility/deprecation-of-http-apis/rules/should-add-deprecation-and-sunset-header-to-responses.md @@ -6,7 +6,7 @@ id: R000069 During the deprecation phase, the API provider should add a `Deprecation` header (see [draft: RFC Deprecation HTTP Header](https://tools.ietf.org/html/draft-dalal-deprecation-header)) and - if also planned - a `Sunset` header (see [RFC 8594](https://tools.ietf.org/html/rfc8594#section-3)) to each response affected by a deprecated element (see [MUST reflect deprecation in API specifications](../../../../global/compatibility/deprecation/rules/must-reflect-deprecation-in-api-specifications.md)). -The `Deprecation` header can either be set to `true` when a feature is disabled, or it can carry a deprecation timestamp at which a replacement is made available and consumers are no longer allowed to use the feature (see [MUST NOT start using deprecated APIs](../../../../global/compatibility/deprecation/rules/must-not-start-using-deprecated-apis.md)). +The `Deprecation` header can either be set to `true` when a feature is disabled, or it can carry a deprecation timestamp at which a replacement is made available and consumers are no longer allowed to use the feature. The optional `Sunset` timestamp indicates when consumers have to stop using a feature at the latest. The sunset timestamp should always offer an appropriate time interval for switching to a replacement feature. diff --git a/api-guidelines/rest/http/headers/rules/should-honor-available-etag-header-on-subsequent-modifications.md b/api-guidelines/rest/http/headers/rules/should-honor-available-etag-header-on-subsequent-modifications.md deleted file mode 100644 index 9f9deb07..00000000 --- a/api-guidelines/rest/http/headers/rules/should-honor-available-etag-header-on-subsequent-modifications.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: R000074 ---- - -# SHOULD honor available `ETag` header on subsequent modifications - -In addition to the normal payload, an optional `ETag` header can be part of the response to a `GET` or `HEAD` request. - -A client should use the `ETag` response header value of a prior request as `If-Match: ` request header on subsequent `PUT`, `PATCH` or `POST` requests for making modifications to a resource. This also applies for services, that introduced the `ETag` header with the sole intention of [improving cachability](./may-use-etag-header-for-caching-resources.md).