Application integration platform guidelines

These guidelines and standards are for the development of Application Programming Interfaces (APIs) for States of Jersey technology

You should always assume that access to a service is through a defined API.

Types of API and preference

The States of Jersey preference is for REST APIs. Representational State Transfer (REST) interfaces are resource-based. You should use them when the interface interacts with a resource, such as a person or an address. 

Generally, REST interfaces are excellent for human consumption, and they're the current preference of cloud and mobile developers.

REST interfaces, especially those designed around change / read / update / delete (CRUD) events, tend to be chatty, so you should consider composing or aggregating services.

      You can consider other types of API if they are better suited, such as:

• Simple Object Access Protocol (SOAP): these interfaces are method-based. The most important aspects of the interface design are the set of supported methods and the data structures of each method
• Message Queue Telemetry Transport (MQTT): these interfaces are event-based. The most important aspects of the interface design are the set of events (emitted or received) and the associated event messages

API guidance and standards

The States of Jersey adopts best practice guidelines specified within the Government Digital Service (GDS) guidance and the United States Government Web API Standards.

The GDS guidance covers both building and consuming APIs.

The US Government Web API standards state: "This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX)."

As well as these guidelines, you should also use the best practice guidelines from the platform being used for development, for example, Microsoft API guidelines.

Web services must be designed with security in mind and follow the security principles of at least:

• privilege
  
• authentication
  
• confidentiality
  
• integrity
  
• availability
  

In addition to the States of Jersey Security Standards, you can use the Open Web Application Security Project cheat sheet.

Both the US Government standards and the Microsoft guidelines use Git repositories and have communities with comments and examples.

Additional API standards

API Versioning

One of the most important considerations is versioning of the API. Version 1 is always easy to deploy but you need to consider future changes and build capability into the design to ensure future releases can be catered for without breaking consumers.

There is no standard for versioning a REST API but there are three possible options, each with their own pros and cons:

• put the version number in the URI
  
• put the version number in an HTTP header
  
• pass the version number as a parameter to the API
  

For REST resources designed, developed and deployed within the States the following guidelines should be used:

• put the version number in the URI and to the left of the resource being provided. For example, http://example.com/v1/MyResource
  
• defer making breaking changes for as long as possible. When a breaking change is made increase the version number, for example http://example.com/v2/MyResource
  
• when consuming a service avoid binding too tightly to the service. This way a minor change in the API is unlikely to cause a breaking change. Follow the Tolerant Reader pattern.
  

You should not need a new version of your API just because you:

• added a new resource
  
• added data in the resource
  
• changed technology, for example Net to Java
  

You may want to consider a new major version for an API if:

• the resource is removed or renamed
  
• critical API parameters are added, removed or renamed
  
• changes to error codes that affect how a client functions or reacts to the service
  

When you produce a new version of an API you'll probably want to retire the old version once all clients have moved over to the new version.

A warning header should be added to the response to notify clients (at a technical level) that the resource is being retired.

For example:

Warning: 299 "Deprecated API: API example.com/v1/MyResource will be deprecated on 2016-12-24T12:00:00Z"

Warning headers are defined in RFC 7234.

Response Codes

The guidelines give three possible response codes to use for REST and although it's good practice to limit the number, there may be cases where you need to return a different HTTP response code, for example:

• to provide better auditing (failed authentication attempts)
  
• give better control of a process
  
• give more detail to an error condition
  

Examples of these are:

Idempotent services

Idempotency guarantees that repeated invocations of a service capability are safe and have no negative side effect. This is important in an environment where server and network failures can lead to unpredictability and lost messages.

For example, if you deposit £100 into a bank account you wouldn't want a service to accept the exact same £100 deposit 10 times. To solve this problem, use unique identifiers, much in the same way as bank notes contain a unique number to prevent fraud. 

Not all methods will be idempotent but generally the HTTP verbs GET, PUT and DELETE are and POST are not.

Partial updates to resources

The HTTP PATCH method is set out in RFC 5789 and designed to support partial resource modifications. However, PATCH isn't safe or idempotent.

The preferred method of partially updating a resource is to define a new resource that encapsulates part of the resource to be modified and accept the PUT method to update the resource. The original resource must include a link to the new resource location.

If the PATCH method is used to allow partial updates to a resource then you should take care with the implementation to make sure it's designed to be called in an idempotent manner.

The body of the PATCH request must be a representation that describes the set of changes that need to be made to the resource and if the server applied the changes successfully then a 200 (OK) response must be returned.

The implementation of the method should be conditional; that is, the use of If-Unmodified-Since and / or If-Match headers by the client. The server must return a 412 (Precondition Failed) if the preconditions do not match.

Dates and times

To address issues with APIs publishing and consuming a date any services designed and deployed by the States will use the ISO 8601 standard for representing dates.

By providing standardisation the ISO format provides the following benefits:

• locale neutrality: the month and date fields are clearly defined which avoids confusion when interacting with international clients, for example 01/03 is 3 January and not 1 March
  
• a time zone offset can be specified as part of the date
  
• the date is consistent and readable
  
• ISO 8601 is supported by a large number of applications and programming languages
  

Broadly the ISO 8601 date and time format is:

Year-Month-DayTHour:Minute:Second:NanoSeconds-TImezoneOffset (or Z for UTC)

For example: 2017-01-04T12:00:00+0000 or 2017-01-04T12:00:00Z

When using ISO 8601 the following rules should also be followed:

• your API should accept any timezone (although the preference would be to use UTC)
  
• your API service should store the date in UTC format
  
• your API should return the date in UTC format
  
• when the time is not needed only use the date
  

There are likely to be cases where these rules don't apply, these instances should be clearly documented with the API.