Cache usage SHOULD be extensively detailed in the description property
to avoid data leaks or the usage of stale data.
This rule should ensure in some way that the api provider
documented extensively the cache usage to avoid data leaks
or usage of stale data.
The no-transform directive can
be used in responses to avoid transforming proxies to
modify (eg. compress) the content.
For now this ruleset tests:
* the presence of following keywords
in the description: max-age, private, no-store, no-cache,
no-transform.
* that one and only one between Expires and Cache-Control is used.
Cache-Control and Expires should not be used in conjunction,
because Cache-Control overrides Expires when max-age is set.
Instead if neither Cache-Control or Expires are set, clients MAY use heuristic cache
like described in RFC7234.
Cache usage SHOULD be extensively detailed in the description property
to avoid data leaks or the usage of stale data.
This rule should ensure in some way that the api provider
documented extensively the cache usage to avoid data leaks
or usage of stale data.
The no-transform directive can
be used in responses to avoid transforming proxies to
modify (eg. compress) the content.
For now this ruleset tests:
* the presence of following keywords
in the description: max-age, private, no-store, no-cache,
no-transform.
* that one and only one between Expires and Cache-Control is used.
Cache-Control and Expires should not be used in conjunction,
because Cache-Control overrides Expires when max-age is set.
Instead if neither Cache-Control or Expires are set, clients MAY use heuristic cache
like described in RFC7234.
Cache usage SHOULD be extensively detailed in the description property
to avoid data leaks or the usage of stale data.
This rule should ensure in some way that the api provider
documented extensively the cache usage to avoid data leaks
or usage of stale data.
The no-transform directive can
be used in responses to avoid transforming proxies to
modify (eg. compress) the content.
For now this ruleset tests:
* the presence of following keywords
in the description: max-age, private, no-store, no-cache,
no-transform.
* that one and only one between Expires and Cache-Control is used.
Cache-Control and Expires should not be used in conjunction,
because Cache-Control overrides Expires when max-age is set.
Instead if neither Cache-Control or Expires are set, clients MAY use heuristic cache
like described in RFC7234.
Paths should be kebab-case (e.g. path-parameter).
See Italian recommendation RAC_REST_NAME_002.
A GET request MUST NOT accept a requestBody
because this behavior is not interoperable.
Moreover intermediaries such as reverse proxies
are allowed to strip the content from GET requests.
See RFC7231 for further information.
Sending a requestBody in a DELETE request
is not considered interoperable.
Moreover intermediaries such as reverse proxies
might strip the content from DELETE requests.
See RFC7231 for further information.
Responses with the following status codes usually expected to include a content, which might have zero length: 200, 201, 202, 203, 206. Responses with status code 204 and 205 MUST NOT include a content. See RFC7231 for further information.
Responses with the following status codes usually expected to include a content, which might have zero length: 200, 201, 202, 203, 206. Responses with status code 204 and 205 MUST NOT include a content. See RFC7231 for further information.
Servers must use https to ensure the origin of the responses and protect the integrity and the confidentiality of the communication.
You can use http:// only on sandboxes environment.
Use x-sandbox: true to skip this kind of check.
Avoid using method names in operationIds because it couples
the API design with the implementation.
An operation that edits an entry can be published with different methods, for example either POST, PUT or PATCH, and while evolving the API you could decide to associate an operationId with another method.
You can use for example
openapi: 3.0.1
...
paths:
/entries:
get:
operationId: list_entries
post:
operationId: create_entry
/entries/{id}:
put:
operationId: upsert_entry
patch:
operationId: edit_entry
Schema of type number or integer must specify a format
to express the associated datatype, eg. int32, int64, ...
You can express similar requirements using the minimum and maximum properties.
See recommendation RAC_REST_FORMAT_004.
Schema of type number or integer must specify a format
to express the associated datatype, eg. int32, int64, ...
You can express similar requirements using the minimum and maximum properties.
See recommendation RAC_REST_FORMAT_004.
To improve interoperability, integer and number formats are constrained to a shared subset.
See recommendation RAC_REST_FORMAT_004.
To improve interoperability, integer and number formats are constrained to a shared subset.
See recommendation RAC_REST_FORMAT_004.
Swagger 2 files are not allowed. Use OpenAPI >= 3.0
You must define a /status path that can be used to health-check the API.
Using this path avoids the arbitrary usage of a server URL for health-check
scope.
The /status endpoint should return a application/problem+json response
containing a successful status code if the service is working correctly.
The service provider is free to define the implementation logic for this path.
"/status" must return a Problem object.
"/status" schema is not a Problem object.
Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users.
Error responses should return one of the media-type
defined in RFC7807:
- application/problem+json
- application/problem+xml
An example of a valid response:
responses:
"503":
content:
application/problem+json:
schema:
...
WARN: This rule is under implementation and just provides an hint.
Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users.
This rule inspects the schema returned by an error response and
verifies whether it contains the main properties defined in RFC7807:
status, title and detail.
An example of a valid payload is
{
"title": "Not Found",
"status": 404,
"detail": "Book does not exist; id: 123"
}
See recommendation RAC_REST_NAME_007.
When a client is either: * throttled out with a 429 status code; * warned about a temporary server issue with a 503 status code; the server should explicitly communicate how long to wait before issuing further requests using the Retry-After header.
Retry-After is defined in RFC7231.
Ratelimiting an API preserves a service and limits attack scenario see API4:2019 Lack of Resources & Rate Limiting.
APIs should use the following headers at least on successful responses:
- X-RateLimit-Limit: number of total requests in a give time window
- X-RateLimit-Remaining: remaining requests in the current window
- X-RateLimit-Reset: number of seconds before the window resets
An example set of headers is the following
X-Ratelimit-Limit: 100
X-Ratelimit-Remaining: 40
X-Ratelimit-Reset: 12
A standardization proposal for ratelimit headers is ongoing inside the IETF HTTPAPI Workgroup. See the draft
API Keys are (usually opaque) strings that are passed in headers, cookies or query parameters to access APIs.
Those keys can be eavesdropped, especially when they are stored in cookies or passed as URL parameters.
security:
- ApiKey: []
paths:
/books: {}
/users: {}
securitySchemes:
ApiKey:
type: apiKey
in: cookie
name: X-Api-Key
URL parameters MUST NOT contain credentials such as apikey, password, or secret.
See RAC_GEN_004