API Usage

The API can be accessed in the following ways:

• From the Swagger UI page directly (test environment only).
  • Only prerequisite: You should have had your own synthetic patients created via SyntPop.
  • Simplest. Good for starting out for the first time.
• From your own client (any environment).

This page focuses mostly on how to access the API from your own client, but also contains info that is useful for accessing the API from the Swagger UI page.

Basics

In order to send a request to the API from your own client, you will need:

• The base URL for the environment you want to access. See the environments and base URLs page for available base URLs.
• The endpoint (relative URL and HTTP method). See the Swagger UI page for a list of all endpoints with descriptions.
• Correct headers and possibly a request body. See headers and request body below.
• Patients that are valid in the given environment. For the test environment, create your own synthetic patients with SyntPop.

The bullet-point list above may have sub-requirements, such as the production environment requiring inclusion in the health network, or the headers requiring HelseID authorization, so do check the links.

Headers

Common Headers

Common headers for all* endpoints:

* The /<version_id>/metadata-endpoint does not require any headers.

Endpoint-Specific Headers

Some headers are specific to the individual endpoints. These headers are listed on the Swagger UI page under each endpoint that has them and are marked with '(header)'.

Request Body

The request body depends on the endpoint used, but the content type will be one of:

• Nothing (no body)
• application/fhir+json - in the case of a FHIR resource
• application/x-www-form-urlencoded - when calling search-endpoints

The Swagger UI page will show which request body is expected for each endpoint.

Resource Types

Since the API follows the FHIR specification, all resources are FHIR resources.

Core Resource Types

The core resource types used in the API are:

• ServiceRequest FHIR profile (hl7norway.gitlab.io) - A request for one or more specimens to be collected from the patient in the future. Service requests are generally submitted to the PaRek API by the requester (rekvirent).
  • ServiceRequest.orderDetail - There is one order detail per requested specimen.
• Specimen FHIR profile (hl7norway.gitlab.io) - A specimen collected from the patient. Each Specimen fulfills a ServiceRequest.orderDetail. Specimens are generally submitted to the PaRek API by the collector (prøvetaker).
• Device FHIR profile (hl7norway.gitlab.io) - A single container containing a specimen. A specimen references one or more devices and these are submitted together with the specimen.

Other Resource Types

Other resource types are more generic resource types:

• CapabilityStatement - Contains information about the API, its endpoints and resources. Returned from the /<api_version>/metadata endpoint.
• Bundle - Bundle of resources. Returned from search endpoints.
• Parameters - Used by named operation endpoints that fall outside basic CRUD.
• OperationOutcome - Contains information about the outcome of an attempted operation. Usually when an error occurs.

Planned Endpoints

This section is for future endpoints that are not yet implemented, and are therefore not documented on the Swagger UI page.

Planned: Limited Search, Returning the ID Only

Note: Not yet implemented. This endpoint may be subject to changes before implementation.

Endpoint: POST /<api_version>/ServiceRequest/$search-ids

Purpose: When there is a need to find the ID of a ServiceRequest without releasing sensitive health data.

• Will support calls from M2M-authenticated clients. See M2M-authentication (not yet implemented).
• This endpoint accepts a Parameters resource in the request body on the form:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "identifier",
      "valueIdentifier": {
        "system": <identifier system>,
        "value": <identifier value>
      }
    },
    {
      "name": "status",
      "valueCode": <status>
    }
  ]
}

• Upon success (zero matches is also a valid success response), the endpoint will return a status 200 response:
  • If zero matches, the response is simplified to having no body (still 200 OK).
  • If one or more matches, the response is a Parameters resource on the form:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "id",
      "valueId": <id of 1st matching ServiceRequest>
    },
    {
      "name": "id",
      "valueId": <id of 2nd matching ServiceRequest>
    },
    ...
  ]
}

Planned: Specimens Collected Without PaRek Integration

Note: Not yet implemented. This endpoint may be subject to changes before implementation.

Endpoint: POST /<api_version>/ServiceRequest/{id}/$set-specimens-collected-externally

Purpose: When the collector is not integrated with PaRek, the requester can notify PaRek that all specimens were collected without integration.

• This endpoint does not expect a request body.
• Will support calls from M2M-authenticated clients. See M2M-authentication (not yet implemented).
• The request will fail if the ServiceRequest is already marked as completed or already has a Specimen registered.
• After a successful call to this endpoint:
  • Specimens may no longer be registered on this service request.
  • The server will automatically mark the service request as completed.