API HMCTS Marketplace Template Repository

This is a template repository for HMCTS Marketplace APIs. It defines naming conventions, structure, and validation tooling for OpenAPI specifications.

The repository template and its associated build workflows are designed to support a single API specification per repository.

🔗 API definitions should follow the HMCTS RESTful API Standards.

Naming Convention

NOTE: Avoid using terms like common, core, base, utils, helpers, misc, or shared. These names often allow for ambiguous ownership and quickly become black holes where cohesion goes to die.

Repository names follow a pattern from generic to specific:

api-{sources-system}-[case-type]-{business-domain}-{name-of-entity}

• sources-system: Some examples are:

  • cp - Common Platform
  • dcs - Crown Court Digital Case System
  • sscs - Social Security and Child Support

• case-type: optional parameter could be:

  • civil
  • crime
  • family
  • tribunal

HMCTS manages all Civil, Criminal, Family (separate from civil), and Tribunal cases.

• business-domain, or also could be known as product-domain

The Common Platform (CP) will be:

• caseingestion
• casematerial
• caseadmin
• casehearing
• schedulingandlisting

Reference Data Repositories

Reference data APIs use the following naming format:

api-cp-refdata-{product-domain}-{name-of-entity}

It could be argued that product-domain should be optional for reference data, placing it under global ownership. But global ownership often means no ownership — and no accountability. Therefore, product-domain is required.

Supporting Documents

The docs directory includes supporting information for the repository:

• API-VERSIONING-STRATEGY.md – How we version APIs using media types and SemVer.
• CHAIN_OF_CUSTODY.md – Steps taken to establish a secure software supply chain and audit trail.
• DATA-PRODUCTS.md – Description of structured data outputs generated by the API.
• GITHUB-ACTIONS.md – Overview of GitHub Actions workflows, including secrets and variables.
• OPENAPI-FILE-CONVENTIONS.md – OpenAPI file and content conventions.
• OPENAPI-SPEC-VERSIONING.md – Rules for evolving OpenAPI specs.

Note the build requires secrets and variables to be available in project settings; see GitHub Actions: Required Secrets and Variables

Post-Template Manual Steps

Setup

• Go to settings of the repository -> General -> check "Automatically delete head branches"
• Import the ruleset .github/rulesets/main-branch-protection.json
  To import the ruleset, follow GitHub’s instructions here:
  👉 Importing a ruleset

Once the ruleset has been successfully imported via GitHub Settings, the new repository no longer requires .github/rulesets/main-branch-protection.json so it should be deleted:

Clean Up

After using this template to create your repository, the following files are no longer needed and should be deleted:

• ./docs/*
• ./src/main/resources/openapi/deleteme

Update the ./README.md to reflect the context of the new created repository

Contribute to This Repository

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines.

License

This project is licensed under the MIT License.