"href": "https://api.example.govt.nz/groups/1219c539-5885-4ab6-a55b-b0de7537c427"

},

{

"rel": "Risk analysts",

"href": "https://api.example.govt.nz/groups/7219c539-5885-4ab6-a55b-b0de7537c42c"

},

{

"rel": "Writers",

"href": "https://api.example.govt.nz/groups/3219c539-5885-4ab6-a55b-b0de7537c42h"

},

{

"rel": "Authors",

"href": "https://api.example.govt.nz/groups/g219c539-5885-4ab6-a55b-b0de7537c425"

}

]

}

In rare circumstances it is possible that an extremely complex search API may run into query string or URL length limitations, although this is probably an indication that the design of the search operation is too complicated. The exact length limit is server- and client-dependent. For example, the Apache server has a default limit of 8KB, Microsoft Information Internet Services (IIS) has a default of 16KB, and many browsers are limited to around 2KB maximum URL length.

Where the total length can potentially exceed 2KB, the only option is to implement the search operation using the POST verb with an appropriately designed request object to contain the search parameters.

Example template

POST /{version}/{namespace}/{search-resource}

Example request

POST /v1/people/person-search?page=5 HTTP/1.1

Host: www.example.com

Content-Type: application/json

{

"startDateBefore":"2010-01-01",

"position": "Manager",

"businessUnit": "Operations",

. . . many other search parameters . . .

}

Example response

HTTP/1.1 200 OK

Content-Type: application/json

{

"pageSize": 10,

"page": 5,

"totalItems": 77,

"totalPages": 8,

"items": [

. . . lots of people objects here . . .

]

"_links": [

{

"rel": "first",

"href": "https://www.example.com/v1/people/person-search?page=1"

},

{

"rel": "prev",

"href": " https://www.example.com/v1/people/person-search?page=4"

},

{

"rel": "next",

"href": " https://www.example.com/v1/people/person-search?page=6"

},

{

"rel": "last",

"href": " https://www.example.com/v1/people/person-search?page=8"

},

]

}

Other considerations include special characters or filters that add additional complexity due to URL encoding requirements. For example, the search function might need to support ‘<’ or ‘>’ operators, or special characters for non-English language support.

Additionally, SQL words should be avoided, as common threat detection filters may block requests containing words such as ‘DROP’, ‘ALTER’ or ‘DELETE’ in case they are SQL injection attacks. For more details, see the following Open Web Application Security Project (OWASP) cheat sheets:

Cross-Site Scripting (XSS) Prevention Cheat Sheet — OWASP

SQL Injection Prevention Cheat Sheet — OWASP

Paging behaviour for search results should be consistent with the interaction as described in section 1.5.6. Query arguments. Pagination can be implemented as a page number and page size, offset and limit, or continuation token, depending on the scale and changeability of the search results.

Note: It is worth pointing out that since the HTTP protocol treats POST operations as unsafe, the result is not cacheable. This applies even if the response has a Cache-Control header included, so consider the performance impacts on the API if this is a high-volume operation.

1.12. Caching

Caching enables faster responses from APIs and reduces server load. It is good for information that is frequently requested but does not change very often. The aim is to retrieve information once but re-use many times.

There are a number of caching methodologies available. This section focuses on 2 types of caching that should be owned and controlled by the provider, primarily for APIs.

1.12.1. Response cache

A response cache is a cache that contains the response to a GET request on a unique resource. The response should be cached as close to the consumer as possible while remaining inside the control boundaries of the agency. Response caches are usually fast, in-memory caches. Many off-the-shelf API gateway / management solutions provide a built-in response cache.

When using a response cache, agencies should ensure that they understand and monitor their cache to ensure that stale objects are kept to a minimum and that they have sufficient system memory to service caching loads. This means ensuring that the cache is refreshed once a user has updated the information or a cache timeout has occurred.

Consider the example in figure 3 of a response cache.

Figure 3: Caching — Sequence diagram

Detailed description of figure

Figure 3 illustrates a caching 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 6 sections and associated steps:

Section 1 — User1 first GET request

User1 sends GET customers / 1234 to API gateway.

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache.

Response cache sends cache miss to API gateway.

API gateway sends process request to providing application.

Providing application retrieves data from agency data.

Providing application sends response to API gateway.

API gateway sends cache response with key ‘cacheid_customers_1234’ to response cache.

The response cache object time to live is 1,800 seconds or 30 minutes.

API gateway sends response to User1.

Section 2 (happens 5 minutes later) — User1 second GET request

In this case, response is cached and valid.

User1 sends GET / customers / 1234 to API gateway.

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache.

Response cache sends cache hit to API gateway.

API gateway sends response to User1.

Section 3 — User2 first GET request

In this case, response is cached and valid.

User2 sends GET / customers / 1234 to API gateway

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache

Response cache sends cache hit to API gateway

API gateway sends response to User2

Section 4 — User1 first PUT request

In this case the response is cached and valid, request is an update, API must invalidate cache.

User1 sends PUT / customers / 1234 to API gateway.

API gateway sends process request to providing application.

Providing application updates data to agency data.

Providing application sends response to API gateway.

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache.

Response cache sends cache hit to API gateway.

API gateway sends invalidate cache to response cache.

API gateway sends response to User1.

Section 5 — User1 third GET request

User1 sends GET / customers / 1234 to API gateway.

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache.

Response cache sends cache miss to API gateway.

API gateway sends process request to providing application.

Providing application retrieves data from agency data.

Providing application sends response with updated data to API gateway.

API gateway sends cache response with key ‘cacheid_customers_1234’ to response cache.

The response cache object time to live is 1,800 seconds or 30 minutes.

API gateway sends response with updated data to User1.

Section 6 (happens 45 minutes later) — User2 second GET request

User2 sends GET customers / 1234 to API gateway.

API gateway sends check cache for key ‘cachedid_customers_1234’ to response cache.

Response cache sends cache miss to API gateway.

Cache object expired.

API gateway sends process request to providing application.

Providing application retrieves data from agency data.

Providing application sends response with updated data to API gateway.

API gateway sends cache response with key ‘cacheid_customers_1234’ to response cache.

The resource is re-cached with a time to live of 1,800 seconds or 30 minutes.

API gateway sends response with updated data to User2.

1.12.2. Object cache