API design
Design and implementation
Use the Zalando RESTful API Guidelines as the reference standard for API design.
The source repository is zalando/restful-api-guidelines.
HMCTS additions
Personal data in URLs
HMCTS services must not transmit personal data in URL paths or query strings. This information can be inadvertently exposed via client, network, and server logs.
Where personal data is required, transmit it in the request body or, where that is not possible (e.g. GET requests), in HTTP headers.
Versioning
Use content type negotiation or endpoint naming to version the API.
Do not make backward incompatible changes to existing endpoints.
See the official guidance in the TGL
Documentation
Use OpenAPI for API documentation.
Maintain a central repository of API documentation. On the Cloud Native Platform, publish your specification to the central API docs repository.
Previous HMCTS fork
HMCTS previously maintained a fork, hmcts/restful-api-standards, last updated in August 2020 and archived in January 2025. Its only HMCTS-specific rule, personal data in URLs, is kept above. Links to the fork in older repositories still resolve but should be updated to point here.