Working with Endpoints

Client Systems wishing to subscribe to a Topic with a rest-hook Subscription must first create an endpoint to which notifications will be sent for future events. To allow for flexibility, multiple Subscriptions can use the same endpoint, or separate endpoints may be set up for each Subscription as required. As well as an address, each endpoint registered with the Spine may optionally include a set of headers which will be sent with each notification sent to the endpoint. These may be configured as required by the Client System, for example, to meet authentication or auditing requirements.

Client Systems choosing to use the event-pull mechanism when subscribing do not need to register an Endpoint with the Spine API.

Create Endpoint

POST /Endpoint

When creating or updating an endpoint, the Spine will send a handshake notification to the URL specified in the address property using the POST method. The endpoint must return a success status, otherwise the endpoint will not be created and an error response will be returned.

Parameters

Name

Type

Description

body

JSON Object (body)

Example

JSON

{
    "resourceType": "Endpoint",
    "status": "active",
    "connectionType": [
        {
            "coding": [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
                    "code": "hl7-fhir-rest"
                }
            ]
        }
    ],
    "address": "https://my.domain.com/notify",
    "header": [
        "Authorization: Bearer my-secret-token-abc-123"
    ]
}

status: Only active is currently supported
address: Must use an ‘https’ scheme and must be well-formed according to the HTTP standard
header: An optional array of headers to be sent with rest hook calls to the endpoint. Each must be formatted as Key-Value pairs, separated by a colon

Responses

Code

Description

201

Created

See response header: X-Logical-Id to obtain the ID of the created record

422

Unprocessable Entity

Get Endpoint

GET /Endpoint/{endpoint-id}

Parameters

Name	Type	Description
`endpoint-id`	String (path)	The ID of the Endpoint to get

Responses

Code

Description

200

Example

JSON

{
    "resourceType": "Endpoint",
    "id": "9ff1c58c-32c9-4f87-bb59-bbf71fbc9cf9",
    "status": "active",
    "connectionType": [
        {
            "coding": [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
                    "code": "hl7-fhir-rest"
                }
            ]
        }
    ],
    "address": "https://my.domain.com/notify",
    "header": [
        "Authorization: Bearer my-secret-token-abc-123"
    ]
}

404

Not Found

Get all Endpoints

GET /Endpoint

Responses

Code

Description

200

Example

JSON

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 2,
    "entry": [
        {
            "resource": {
                "resourceType": "Endpoint",
                // etc
            },
            "search": {
                "mode": "match"
            }
        },
        {
            "resource": {
                "resourceType": "Endpoint",
                // etc
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

Update Endpoint

PUT /Endpoint/{endpoint-id}

Parameters

Name	Type	Description
`endpoint-id`	String (path)	The ID of the Endpoint to Update
`body`	JSON Object (body)	JSON model as for Create

Responses

Code	Description
204	Success - No Content
404	Not Found

Delete Endpoint

DELETE /Endpoint/{endpoint-id}

Only Endpoints which are not referenced by any Subscriptions may be deleted.

Parameters

Name	Type	Description
`endpoint-id`	String (path)	The ID of the Endpoint to Delete

Responses

Code	Description
204	Success - No Content
404	Not Found