An object cache is used to cache objects that are fundamental to the function of an API but may not change on a regular basis. For example, an API may include a tax code validation step. Tax code references are held in a backend database. To prevent redundant requests to the database, the API layer could cache tax codes in its object cache and refer to these until the cache becomes invalid. Figure 4 details an example sequence.

Figure 4: Object cache — Sequence diagram

Detailed description of figure

Figure 4 illustrates an object sequence diagram in a Unified Modeling Language (UML) sequence diagram showing interactions between different actors in the use case. The sequence is divided into the following 4 sections and associated steps:

Section 1 — User PUT request

User sends PUT / returns / paye / 1234 to API.

API validates tax code.

API checks object cache for key ‘cacheid_tax_codes’.

Object cache sends cache miss to API.

API retrieves tax codes for object cache from agency data.

API populates object cache with key ‘cached_tax_codes’.

Tax codes cache object time to live is 36,000 seconds or 10 hours.

API checks tax code in object cache.

API sends process request to providing application.

Providing application updates agency data.

Providing application sends response to API.

API sends response to User.

Section 2 (happens 5 minutes later) — User PUT request

User sends PUT /returns / GST / 9876 to API.

API validates tax code.

API checks object cache for key ‘cacheid_tax_codes’.

Object cache returns cache hit to API.

Cache object is cached and valid.

API checks tax code in object cache.

API sends process request to providing application.

Providing application updates agency data.

Providing application sends response to API.

API sends response to User.

Section 3 — Tax codes updated in backend database

Agency administrator updates tax codes in agency data.

Agency data sends cache refresh request to API.

API updates object cache with key ‘cached_tax_codes’.

Tax codes object time to live is 36,000 seconds or 10 hours.

Section 4 (happens 11 hours later) — User PUT request

User sends PUT / returns / corporation / 7654 to API.

API validates tax code.

API checks object cache for key ‘cacheid_tax_codes’.

Object cache sends cache miss to API.

Tax codes cache object expired.

API retrieves tax codes for object cache from agency data.

API populates object cache with key ‘cached_tax_codes’.

Tax codes object time to live is 36,000 seconds or 10 hours.

API checks tax code in object cache.

API sends process request to providing application.

Providing application updates agency data.

Providing application sends response to API.

API sends response to User.

1.13. Error handling

Learn more about how important errors in the development of API are being handled.

Error handling is important because API consumers see the API as a black box, and when an error occurs they need to know how to handle it. Therefore error responses need to be informative yet avoid information leakage about the internals of the backend system. Errors should be handled in both a human- and machine-consumable way. When an error occurs, the response body should contain:

the HTTP status code

an API-specific error code, which API support staff will be able to look up to identify what has gone wrong

a human readable error message (possibly including selective technical details if the API is a development / test release for developer consumption only).

1.13.1. HTTP status codes

RESTful APIs should always use the standard HTTP error responses when an error occurs, but different codes may be pertinent depending on the HTTP verb being used and the quantity of data being retrieved (for example, single item versus list / collection of data).

For a tutorial, see HTTP Status Codes — REST API Tutorial

The following table gives an example of good practice use of HTTP error codes.

Table 6: HTTP status codes

Code

Meaning

Description

GET response status codes

200

OK

The request was successful, and the response body contains the representation requested.

302

FOUND

A common redirect response — you can GET the representation at the URI in the Location response header.

304

NOT MODIFIED

Your client’s cached version of the representation is still up to date.

401

UNAUTHORISED

The supplied credentials, if any, are not sufficient to access the resource.

404

NOT FOUND

The requested representation was not found.

429

TOO MANY REQUESTS

Your application is sending too many simultaneous requests.

500

SERVER ERROR

An internal server error prevented return of the representation response.

503

SERVICE UNAVAILABLE

We are temporarily unable to return the representation. Please wait and try again later.

POST or PUT response status codes

200

OK

The request was successful, and the resource was updated. The response body contains the updated representation.

201

CREATED

The request was successful, a new resource was created, and the response body contains the representation.

400

BAD REQUEST

The data given in the POST or PUT failed validation. Inspect the response body for details.

401

UNAUTHORISED

The supplied credentials, if any, are not sufficient to create or update the resource.

404

NOT FOUND

The representation was not found.

405

METHOD NOT ALLOWED

You cannot POST or PUT to the resource.

429

TOO MANY REQUESTS

Your application is sending too many simultaneous requests.

500

SERVER ERROR

We could not create or update the resource. Please try again later.

DELETE response status codes

204

OK

The request was successful. The resource was deleted.

401

UNAUTHORISED

The supplied credentials, if any, are not sufficient to delete the resource.

404

NOT FOUND

The representation was not found.

405

METHOD NOT ALLOWED

You cannot DELETE the resource.

429

TOO MANY REQUESTS

Your application is sending too many simultaneous requests.

500

SERVER ERROR

We could not delete the resource. Please try again later.

501

NOT IMPLEMENTED

The HTTP method is not supported by the server and cannot be handled.

Note: Where a consumer attempts to call a non-existent API end point, respond with a ‘501 Not Implemented’ status code.

1.13.2. API-specific error code

Error responses need to supply enough information to allow the API consumer to react appropriately to the error, yet not give away too much. But when a critical error occurs it is important for the API provider to be able to trace the root cause and fix it as soon as possible.

One way of achieving this is to return an API-specific error code in the response to the consumer. When the consumer reports the error to the API support team, the consumer can relate the associated API-specific code. The support team can then look this code up and ascertain exactly what has gone wrong and who needs to address it.

1.13.3. Human-readable error message

The human readable error message should be as informative as is useful to an end customer, without offering too many technical details (for example, “An account with this ID already exists.”).

It is important to avoid revealing system information in the human readable response, such as composition of the backend system like component names, as this informs malicious consumers as to what vulnerabilities and back doors to look for. It is also important not to confirm or deny sensitive information, such as username in a username / password combination, as this informs potential attackers which criteria they have got correct.

A07: 2022 Identification and Authentication Failures — OWASP

In non-production instances of the API it may be appropriate to offer more verbose error messages with some technical detail (for example, “Body should be a JSON object.”). However, it is still recommended not to reveal too much about the internal systems that underpin the API, as non-production systems still reflect a lot of the composition of production.

Example

{