API producer standards

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

Contents

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.

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

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

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?