Healthcode API bundles contain many list and search APIs to enable searching and bulk retrieval of resources. Following are some of the common interface aspects of such list APIs.

Request

All list and search APIs by default operate with HTTP method GET and accept input parameters as query parameters. Where a specific API requires a different HTTP method, it’s specified within the specific API section.

Multiple search parameter values

For any search APIs using multiple values, comma (,) can be used as a separator. Example: practitioner=SP00123, SP00456, ..

However, refer to the individual API documentation to know the specific fields that can support multiple values.

Sorting

List and search APIs accept a _sort query parameter to enable sorting by one or more fields.

Incremental data retrieval

Data listing APIs support a date/time _since request query parameter to enable incrementally synchronised data. The parameter accepts a date/time value and returns all records newly created or updated since the input date/time. Only data for a maximum period of 90 days from today are considered so application implementations must ensure they periodically synchronise the datasets.

Requesting inclusion of additional resources

The list and search APIs support the _include and _revinclude parameters, as specified within FHIR specification here, to enable integrating systsmes to request inclusion of additional resources in the returned resultset.

An example is, when searching for available slots within ICE service, a caller may request including Schedule and Practitioner resources in the returned resultset to avoid having to make separate API calls to retrieve the corresponding data. (However, please note the attributes included within the additional resources may be a subset of the resource’s full dataset, as deemed relevant by the server for the specific API’s context).

Where relevant, the specific APIs document the additional resources available to be requested.

Pagination

Pagination can be controlled by the following request query parameters.

• page – If not specified the first set of records will be returned, with the number of records returned limited by value of count parameter, if specified. When a value is specified, a set of records starting from an offset of (page - 1) * count will be returned. When supplied, the value must be 1 or above and defaults to 1.
• count – Specifies the page size – i.e. the maximum number of records per page. The server is not bound to return the number requested, but will not return more. The value can be from 1 to 250 and defaults to 100.
  As an exception a few specific APIs may support a higher or lower page size than the default range, considering performance criteria, size and amount of data in consideration. In such cases details of the allowed page size is documented under the specific API section.

When the total number of matched records is greater than the page size – as specified by the count parameter – the response will include links for next/previous pages.

Where the caller requested inclusion of additional resources as specified under previous section above, such added resources are not counted towards the page count. In few cases, the server itself may voluntarily return additional resources in the returned resultset – for example, returning resources referenced from the main entity being processed under current request. Such additional resources are also not counted towards the page count. In effect, the returned resultset may indeed consist of more number of resources than indicated by the page count.

Response

Where not explicitly specified otherwise, the list and search APIs always return a paginated resultset as a Bundle resource.

Below snippet represents a sample bundle response.

{
    "resourceType": "Bundle",
    "meta": {
        "tag": [
            {
                "code": "page",
                "display": "1"
            },
            {
                "code": "count",
                "display": "16"
            },
            {
                "code": "maxCount",
                "display": "16"
            }
        ]
    },
    "type": "searchset",
    "total": 16,
    "entry": [
        {
            "fullUrl": "https://ref.api.dev.healthcode.co.uk/organization/ins/agb",
            "resource": {
                "resourceType": "Organization",
                "id": "agb",,
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                "code": "ins",
                                "display": "Insurance Company"
                            }
                        ]
                    }
                ],
                "name": "Aetna Global Benefits"
            }
        },
        {
            "fullUrl": "https://ref.api.dev.healthcode.co.uk/organization/ins/awc",
            "resource": {
                "resourceType": "Organization",
                "id": "awc",,
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                "code": "ins",
                                "display": "Insurance Company"
                            }
                        ]
                    }
                ],
                "name": "Allianz Worldwide Care"
            }
        },
        .
        .
        {
            "fullUrl": "https://ref.api.dev.healthcode.co.uk/organization/ins/wpa",
            "resource": {
                "resourceType": "Organization",
                "id": "wpa",,
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                "code": "ins",
                                "display": "Insurance Company"
                            }
                        ]
                    }
                ],
                "name": "WPA"
            }
        }
    ]
}

The type field can be one of collection, searchset or history.

The entry records may also return an OperationOutcome resource in case of error scenario.

No-match searches

When a search API finds no matching resources to return – or a list API finds no relevant data – the APIs will return success status, HTTP 200, but with empty resultset in the request body.