Skip to main content

Hosting APIs

It’s likely that your Kotlin application will provide APIs to be called by your front end, other APIs or both. We generally use Spring Web MVC to host API resources.

Note that the reactive stack Spring Webflux has been trialled in places, but we’ve generally found that Spring MVC performs well enough and is simpler.

General Principles

  • Prefer thin controllers. Your service layer should do the heavy lifting.
  • Use DTOs in your API. Don’t expose your internal DB model.
  • Secure your API with Spring Security and roles.
  • Document your API with an OpenAPI specification.
  • Avoid breaking changes to your API.
  • Use the standard ErrorResponse from our Kotlin library when things go wrong.

Securing your API

Spring Security is automatically added by our Kotlin library and configured to use HMPPS Auth as its authentication server. This means any clients will need a valid JWT issued by HMPPS Auth to call your API.

An additional layer of security is provided by limiting the roles supported by your API using Spring Security’s method security. These roles should then be declared in your API using Spring’s @PreAuthorize annotation at the class or method level (of which there are many examples). Clients will then need to request these roles in order to call your API.

If your API is public facing you should also consider using the ModSecurity WAF. This is supported by our HMPPS generic service helm chart, see the helm values files for examples of usage.

Documenting your API

We generate OpenAPI specifications with springdoc. We’ve found generating documentation from code to be more reliable than generating code from documentation.

The Kotlin template provides some simple OpenApiConfiguration that needs some blanks filling in. You should enter details for the servers, tags, components and info sections - see the many examples for inspiration. Also consider using a HTML description for nicer formatting in your top level information section.

Given you should be using Spring request annotations on your controllers and handler annotations on your parameters, your endpoints and models should now appear in the OpenAPI specifications. You can add more documentation using various swagger annotations.

Don’t forget to update the link to the OpenAPI spec. in your README.