Skip to main content

Service naming

Service name

Naming a service is a part of the service design process and should involve members of the team from a variety of disciplines.

There’s advice on naming in both the MoJ technical guidance and the Gov Service Design Manual.

By convention we tend to use the service name in the DNS domain used by the service.
As this will have a size limit try not to make your service name too long - a maximum of 25 characters should be ok.

Prefix

To allow us to clearly identify owners for a repo, service or namespaces, names must be be prefixed hmpps-.
This allows us to determine which agency is responsible for the upkeep and maintanance of it.

It also allows us to effectively namespace common components, by calling our authorization service hmpps-authorisation-service, it give space for an laa-authorisation-service and an opg-authorisation-service.

Suffix

We denote services that publish APIs with the -api suffix.
This helps immediately denote it’s responsibility without having to search for additional context.

Some teams choose to follow a similar pattern for frontend services and add the -ui suffix.

Alphas / Proof of concepts

Naming is difficult and it can be difficult to come up with good names if you’re not entirely sure about the scope of your service and how it fits in with the rest of the ecosystem.

Renaming a service / namespace is time consuming and it can be tricky to ensure everything is renamed consistently.

If you’re starting an alpha or proof of concept and not entirely sure about the name but wish to start development, then denote that the service is not going to production as is, by adding the -poc suffix before any other suffix.

for example:

  • hmpps-create-and-vary-a-licence-poc-api
  • hmpps-create-and-vary-a-licence-poc-ui

Consistency

We try to aim for some consistency across repos, domains, services and namespaces.

To demonstrate this with an example:

Service Name

Assess for early release

Namespaces:

Repos:

  • API: hmpps-assess-for-early-release-api
  • Frontend: hmpps-assess-for-early-release-ui or hmpps-assess-for-early-release

Domains:

For domains we drop the hmpps prefix and any ui suffix.
For dev and preprod we add a suffix which denotes the environment to the service name

Frontend:

  • dev: https://assess-for-early-release-dev.hmpps.service.justice.gov.uk
  • preprod: https://assess-for-early-release-preprod.hmpps.service.justice.gov.uk
  • prod: https://assess-for-early-release.hmpps.service.justice.gov.uk

API:

  • dev: https://assess-for-early-release-api-dev.hmpps.service.justice.gov.uk
  • preprod: https://assess-for-early-release-api-preprod.hmpps.service.justice.gov.uk
  • prod: https://assess-for-early-release-api.hmpps.service.justice.gov.uk

There may be situations and there isn’t a one to one relationship and multiple services sit inside the same namespace.

Exceptions

If you have believe there is a compelling reason to not follow these guidelines for your service then discuss this with the lead architect or lead developer in your area.

This page was last reviewed on 21-Jan-2025, next review will be on 01-Jun-2025.
Edit this page here.