API guidelines — Part C: API development 2022

Learn about the technical details in developing an API (Application Programming Interface) and the standards that need to be met.

1. API design and development-

This section covers key considerations such as good API design, correct use of the Hyper Text Transfer Protocol (HTTP), version control and various technical standards.

1.1. API artefacts

Some fundamental artefacts that comprise an API deliverable are:

interface specification, accessible via some form of catalogue

API code and policies

tests

Service Level Agreement (SLA) for the API, identifying performance, availability.

These artefacts are the responsibility of the API developer and should be mandated as a minimum set of deliverables when developing an API. All of these artefacts must be managed in a source code management system so that changes can be tracked and collaborative development can be performed.

1.2. API design

Learn about good API designs and how it will attract other developers.

Application developers will invest heavily in using your API. They will invest in learning the design and behaviour of your API, in developing and testing around your API and may even invest in developing an entire business model on your API.

Good API designs will attract more developers. Conversely, bad API designs will drive away developers and drive up costs — support costs, maintenance costs and operating costs.

1.2.1. When an API is appropriate

In the past, the default reaction to a requirement for capability has been to develop a web application. This is now gravitating towards APIs as the default. So, when is it better to build an API than a web application?

Situations where an API may be more appropriate are when:

commercial organisations or non-governmental organisations (NGOs) are screen scraping data from the agency’s website

the agency holds a single authoritative source of the truth

there is a need for (near real time) information exchange with a partner agency

parts of a business process are (or may be) outsourced

the agency’s service can be included as part of a larger business process

the agency needs internal systems to interact with cloud-based commercial off-the-shelf (COTS) solutions (software as a service (SaaS))

businesses require easy access to (public) information

commercial organisations want to build capability into their own applications that will benefit the public (mobile / web applications)

the agency expects other parties to act as agents or intermediaries for their services

the agency expects to support service delivery across multiple channels.

1.2.2. Types of API

There are several different types of API and the type you choose may depend on the technical use cases that you apply to both consumption and provision of your API.

Table 1: Types of API

API type

Description

Usage

Representational State Transfer (REST)

REST is the most common and well understood API type. REST should be considered an architectural style for developing distributed hypermedia systems. There is a wealth of information and tooling to support the definition and creation of REST APIs. Typically, a REST API will have a well-defined and strongly-typed schema definition (OpenAPI) where strict compliance can be achieved.

Creating a distributed system where a set of API resources are well defined.

If medium latency resource creation or modification (POST, PUT, DELETE) is required then typically a REST API is a better fit.

Typically used for synchronous interactions.

GraphQL

GraphQL is an open source query and manipulation language developed by Facebook primarily designed to empower API consumers to consume only the data that they require.

A common criticism of REST is that only the entire resource is available for consumption, sometimes referred to as ‘over fetching’, however with GraphQL the client decides the data that it requires. GraphQL also has a strongly-typed schema (GraphQL Schema Definition Language (SDL)).

An API that has a widely distributed client set with a variety of data requirements. Particularly well suited to high read (GET) clients.

Asynchronous APIs

AsyncAPI is an open source initiative to create an event-driven and asynchronous API standardisation and development tooling.

The AsyncAPI specification, inspired by the OpenAPI specification, describes and documents event-driven APIs in a machine-readable format.

Creating distributed systems where a set of API resources are well defined. Typically used for asynchronous interactions and event-driven architectures.

Also useful when developing APIs that front workflows or long running orchestrations.

gRPC

gRPC is a modern open source high performance Remote Procedure Call (RPC) framework that can run in any environment.

In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object, making it easier for you to create distributed applications and services.

This is enabled by a formal Interface Definition Language (IDL). gRPC utilises Protocol Buffers by default, you can make it work with other data formats, such as JavaScript Object Notation (JSON).

Creating distributed systems that require highly performing and scalable APIs.

gRPC makes use of binary data rather than just text which makes the communication more compact and more efficient.

Figure 1 demonstrates a combination of a synchronous API and an asynchronous API.

Figure 1: Synchronous and asynchronous claims API

Detailed description of figure

Figure 1 illustrates an asynchronous and synchronousclaims API in a Unified Modelling Language (UML) sequence diagram. It shows interactions between different actors in the use case. The sequence is divided into the following 4 sections and associated steps:

Section 1 — Register

Service provider system sends POST / register to claims API.

This call is to enable the service provider to register their notification endpoint. Note that this is illustrative only. In reality most consumers will register with an agency using a developer portal or equivalent and create client application credentials with registered notification endpoint(s).

Claims API sends return registration details to service provider system.

Section 2 — Create claim (synchronous API process)

Customer sends access funded product or service to service provider.

Service provider sends create claim details to service provider system.

Service provider system sends register claim details to claims API.

Claims API sends create claim details to agency core system.

Agency core system creates claim and assigns to workflow.

Agency core system returns claim identifier (ID) and status to claims API.

This interaction is illustrated as a RESTful API call for the purposes of this example.

Claims API returns claim ID and status to service provider system.

Service provider system returns claim ID and status to service provider.

Service provider delivers service update to customer.

Section 3 — Subscribe to events

Service provider system sends SUB claims / (claimed) to claims API.

Section 4 — Receive updates (asynchronous API process)

Agency core system provides workflow update.

Agency core system sends PUB claims / (claimed) to claims API.

Claims API receives subscription message to service provider system.

Alternative to 15:

15a. Claims API sends hook notification to notification endpoint.

15b. Notification endpoint forwards notification to service provider system.

Service provider system notifies service provider.

Service provider notifies customer.

View larger image (PNG 250KB)

Figure 1 has 2 associated API specifications. The first is an OpenAPI specification that describes the ‘create claim’ and ‘get claim’ RESTful interactions and the second is an AsyncAPI specification that describes the ‘receive updates’ interaction. These example specifications have been provided in Appendix D.