Endpoints

The Pasientens Prøvesvar API currently provides the following endpoints:

• Metadata - <base-url>/metadata
• DiagnosticReport/_search - <base-url>/DiagnosticReport/_search
• Observation/_search - <base-url>/Observation/_search

Use the links above for details about the individual endpoints.

The _search Endpoints

Currently two of the endpoints are _search endpoints. Though they have their individual detail pages, they also have much in common, which is described here.

Parameters

The _search endpoints accept POST requests with parameters in the body (x-www-form-urlencoded). The parameters can be divided into the following categories:

• Filtering by properties. See the individual endpoint detail pages. (Links are above.)
• Including related resources via _include and _revinclude
• Sorting via _sort
• Pagination via _count and _skip

Interpreting the Response

Each _search endpoint returns a Bundle JSON on success. The resources contained in the entry property can be divided into three:

• Matching resources: Resources matching the search filter. They are entries with "search": { "mode": "match" }.
• Included resources: Related resources requested via _include and/or _revinclude. They are entries with "search": { "mode": "include" }.
• OperationOutcome: Possibly an OperationOutcome entry with information or a warning. It is an entry with "search": { "mode": "outcome" }.

For more info about how a Bundle works, see Bundle in the FHIR documentation.

Including Related Resources via _include and _revinclude

The _search endpoints allow for the inclusion of related resources via the parameters:

• _include: Include resources referenced directly by a matching resource.
• _include:iterate: Include resources referenced by a matching or included resource. (recursive)
• _revinclude: Include resources that directly reference a matching resource.
• _revinclude:iterate: Include resources that reference a matching or included resource. (recursive)

Each of the above supports multiple values, either by comma-separating the values or by duplicating the keys. E.g.:

_include=DiagnosticReport:based-on,DiagnosticReport:specimen

OR

_include=DiagnosticReport:based-on
_include=DiagnosticReport:specimen

Here is a diagram showing all supported values:

---
title: "Figure: Inclusion diagram"
---
flowchart TD
    A[DiagnosticReport] -- DiagnosticReport:result --> B[Observation]
    A -- DiagnosticReport:specimen --> C[Specimen]
    B -- Observation:specimen --> C
    B -- Observation:performer --> D[PractitionerRole]
    A -- DiagnosticReport:performer --> D
    A -- DiagnosticReport:based-on --> E[ServiceRequest]
    B -- Observation:has-member --> B
    E -- ServiceRequest:requester --> D

While _include and _include:iterate both include resources by following the direction of the arrows, _revinclude and _revinclude:iterate include resources by going in the opposite direction.

Note: We do not currently support reverse including from PractitionerRole resources. E.g. _revinclude:iterate=Observation:performer would have no effect.

Sorting via _sort

The _sort parameter lets you specify the order in which matching resources are returned.

Note: As mentioined in the includes section, you may specify that related resources are included in the result. These will always appear after all the matching resources, and the order of included resources is unspecified.

You can sort the results in ascending or descending order. For descending order, prepend the value with a hyphen (-), e.g. _sort=-date.

See the individual detail pages for each endpoint (of type .../_search) to see which properties the _sort parameter supports. The endpoints are listed at the top of the page or in the side menu.

Pagination via _count and _skip

Pagination can be achieved by using the following parameters:

• _count: How many matching resources to return. Default value: 50
• _skip: How many matching resources to skip. Default value: 0

Note: Although the returned Bundle has pagination links in the link property, the links don't work as is. The links show _count and _skip as query parameters, but in reality they are part of the body.

Summarizing with _count=0

Sometimes one may want to know if there are mathcing resources without returning any.

Since a Bundle has a total property which gives the total number of matching resources across all pages, using _count=0 is a good way to simply count all matching resources without returning any.