Conditional Request

_{Published: 20 August 2023}

Known Uses

The combination of ETags with the header parameter If-None-Match is commonly used in Dutch Government APIs. Example: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/VNG-Realisatie/zaken-api/master/src/openapi.yaml#/resultaten/resultaat_retrieve (see operation GET /resultaten/{uuid}). This example even illustrates the usage of multiple ETags. Furthermore in this API the operation HEAD is implemented to check whether the cache is stale or up to date. Using HEAD instead of GET in order to just fetch the most current ETag value is always an option to save bandwidth.

There are no examples of implementations of the If-Modified-Since in combination with ETag.

Conditional Requests are also used to support concurrency control in HTTP. The header If-Match and If-None-Match can be used.

Known uses are:

• In the Energy sector we utilize this mechanism when during registration of Power generating Modules the connection fails.
• Related to this is the usage of the Idempotency-Key for safely retrying requests without accidentally performing the same operation twice. This can be classified as an implicit Conditional Request: https://stripe.com/docs/api/idempotent_requests
• Zalando: https://opensource.zalando.com/restful-api-guidelines/#182
• Otto: https://api.otto.de/portal/guidelines/r000060
• Atlassian: https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/#caching

Discussion Input

Caching is an API capability related to confidentiality. In case of privacy sensitive information response caching is not allowed.

Recommended Reading

• Principles of Web API Design (Higginbotham 2021): Conditional Requests Appendix (page 312)