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.

Deployable Components within a service will likely reflect the service name:
The service Assess for early release has a frontend component: hmpps-assess-for-early-release-ui

Prefix

To allow us to clearly identify owners for a repository, deployable component 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 components that publish APIs with the -api suffix.
This helps immediately denote it’s responsibility without having to search for additional context.

We denote components that publish a user interface with the -ui suffix.

For any components which don’t fall into the category of UI or API, some sort of distinguishing suffix is recommended.

Where two or more components have exactly the same prefix, by adding a suffix, it is easier to create filters for searching through logs, and creating alerting rules.

DNS names :

For DNS names 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

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

At a later point, once you have resolved issues around scope and naming, you can promote the service to become a -dev environment with an appropriate name.

Consistency

We try to aim for some level of consistency across repositories, components, domains, services and namespaces.

To demonstrate this with an example:

Service Name

Assess for early release

Namespaces:

Components:

The Assess for early release service has two components, each in their own repository.
The name of the repositories are identical to the name of the components.

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

Domains:

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 14-April-2025, next review will be on 01-Oct-2025.
Edit this page here.