Skip to main content
HMCTS API Marketplace

Beta This is a new service. Help us improve it by giving feedback.

Welsh translation in progress

This service is being translated. Content that has not been translated yet is shown in English.

API producer standards

Standards and requirements for listing an API on the HMCTS API Marketplace.

Contents

  1. Technical requirements
  2. Eligibility criteria
  3. Specification quality
  4. Data governance

These standards are based on the HMCTS RESTful API Standards and the AMP Catalogue onboarding process. If you have questions, contact the marketplace team.

1. Technical requirements

Your API must meet the following technical requirements before it can be listed on the marketplace.

OpenAPI 3.x specification

Your API must have a valid OpenAPI 3.x specification file at this path in your repository:

src/main/resources/openapi/openapi-spec.yml

The specification must include:

  • info.title — a clear, human-readable API name
  • info.description — a plain-English summary of what the API does
  • info.version — the current version, stamped automatically from the GitHub release tag
  • at least one path with at least one operation

Servers block

The servers block must follow the standard HMCTS pattern. Do not use SwaggerHub virtual server URLs.

Warning Do not hand-bump the version. It is stamped automatically when you cut a GitHub release.

Spectral linting

Your specification must pass the standard Spectral OAS3 ruleset with no errors.

GitHub Actions workflow

Add .github/workflows/publish-api-docs.yml to your repository to publish documentation automatically on each release. This triggers the shared amp-catalog workflow, pinned to @v1.

2. Eligibility criteria

Warning Only external APIs may be listed. Internal APIs must not be exposed publicly via GitHub Pages.
API eligibility by type
API type Eligible? Notes
External, documentation-only Eligible Spec is world-readable via GitHub Pages
External, with mock execution Eligible Try-it disabled; documentation only in the marketplace
Internal / developers only Not eligible Must wait for the APIM Developer Portal

Your API repository must also be public on GitHub. The documentation site is served via GitHub Pages and must return HTTP 200 at https://hmcts.github.io/<repo-name>/ before your listing goes live.

3. Specification quality

Your OpenAPI specification should meet the following quality standards. These directly power the information shown on each API’s detail page.

Title
Clear, human-readable name — not the repository slug.
Plain-English description
A consumer-focused summary of what the API does, who it is for, and what data it returns. Shown under “What does this API do?”.
Contact email
A real team inbox — not the marketplace team’s address.
Endpoint summaries
Every operation must have a summary and a description.
Schema definitions
All request and response bodies defined as named schemas, with property descriptions.
Security scheme
Authentication method declared, for example bearerAuth, and applied to all protected operations.
Error responses
400, 401, 404 and 500 responses documented for each operation.

4. Data governance

As an API producer you are a data controller, or a joint data controller, for the data exposed through your API.

Data sharing agreements

Warning Do not approve access to any APIs without approval from the Data Access Panel (DAP).

Data classification

Eligibility by data classification
Classification Eligibility
Official Eligible - standard data protection controls required
Official-Sensitive Eligible with enhanced governance - formal DSA required
Secret / Top Secret Not eligible for marketplace listing
Full detail on the legal framework, data minimisation, audit, breaches and accountability is set out in the Data Governance Standards, which are being moved into this service.

Ready to publish?

Submit an API for publication