JFT ReadAPI Overview

The ReadAPI includes endpoints for retrieving events and event status. As suggested by FHIR, the resource types used to represent events are a part of the endpoint addresses. The resource types currently supported are:

• Bundle
• Composition
• MedicationDispense

Retrieving events

Event retrieval is supported by both GET and POST requests.

• GET is the primary and recommended way to search events.
• POST is also supported on the _search endpoints for clients that prefer sending search parameters in the request body.
• POST can be useful to avoid problems related to URL length limitations, while still supporting complex queries.
• Keyset pagination (also known as seek pagination) is used to limit the amount of events returned per request. This provides better performance for large datasets and avoids issues like skipped or duplicate records when data is modified while paginating.
• An opaque cursor parameter can be used to retrieve the next page of results. The API will respond with a FHIR Bundle that includes a next link containing the cursor.
• Parameter _lastUpdated is used to limit the result set based on when events were updated in JFT.
• Parameters _tag and _tag:not are used to limit the result set based on whether journaling was acknowledged for the event.

The endpoints are on the format: GET /v1/<ResourceType> and POST /v1/<ResourceType>/_search

For example: GET /v1/Composition or POST /v1/Composition/_search retrieves events submitted as a FHIR Composition resource

Pagination Example:

To retrieve the first page of results with a limit of 10 items, you would include _count=10 in your request body (for POST) or query string (for GET).

You can also specify the sorting order using the _sort parameter. By default, results are sorted ascending by last updated time (_sort=_lastUpdated). To sort descending, use _sort=-_lastUpdated as per FHIR conventions.

Using GET:

http GET /v1/Composition?_count=10&_sort=-_lastUpdated

Using POST:

POST /v1/Composition/_search
Content-Type: application/x-www-form-urlencoded

_count=10&_sort=-_lastUpdated

The response Bundle includes self and next link elements. The next link points to a GET endpoint and carries forward pagination state and query constraints:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://api.read.jft.test.nhn.no/v1/Composition?_count=10&_sort=-_lastUpdated"
    },
    {
      "relation": "next",
      "url": "https://api.read.jft.test.nhn.no/v1/Composition?cursor=ZXlKTVlYTjB..."
    }
  ],
  ...
}

To fetch the next page, you can follow the next link via HTTP GET. If you prefer using POST, you can also submit the opaque token from the cursor query parameter in the request body:

POST /v1/Composition/_search
Content-Type: application/x-www-form-urlencoded

cursor=ZXlKTVlYTjB...

Key constraints for Cursors:

• You should treat the cursor value as completely opaque. Do not attempt to decode or modify it.
• Combining search filters (_tag, _lastUpdated) with a cursor is not allowed and will result in a validation error.
• When a cursor is provided, the _sort parameter is ignored. The sort direction is fixed by the cursor and cannot be changed mid-pagination.

Retrieving event status

The status of a specific event is retrieved by making GET-requests to the $status endpoints.

The endpoints are on the format: GET /v1/<ResourceType>/<ResourceId>/$status

For example: GET /v1/Bundle/123/$status retrieves status for an event submitted as a FHIR Bundle resource with resource ID 123 (resource IDs are actually represented as GUIDs).

The response to a successful status requests is a simple JSON object (i.e. not a FHIR resource):

{
  "registered": "2025-02-14T12:01:02+01:00",
  "read": "2025-02-14T13:13:13+01:00",
  "journalingAcknowledged" : "2025-02-10T18:17:16+01:00",
  "failed": null
}

The fields mean:

• registered: The time when a submitted event was processed by JFT.
• read: The time when the event was retrieved for the first time (or null if unread).
• journalingAcknowledged: The time when an journaling acknowledgement was submitted for the event (or null if not ack'ed)
• failed: To be defined

Required claim

The orgnr_parent claim is required in the access token for all endpoints. Its value must be the organization number of the municipality's main entity.