Profiles & Operations > Interaction: Read Subscription

Interaction: Read Subscription

The Read Subscription interaction retrieves the details of an existing subscription. This interaction allows a subscriber or system to query the subscription registry to obtain information such as the subscription status, filtering criteria, notification endpoint, and other metadata. It ensures that subscribers can verify, manage, and maintain their active subscriptions within the Ontario Health ecosystem.

Scope

This interaction involves a request by a Point of Service system to read Subscription. The request is received by the Subscription service which reads and returns requested Subscription and an OperationOutcome resource if applicable.

Interaction Sequence Diagram

Specification

Read Subscription Request

The Read Subscription shall retrieve the specified FHIR Subscription resource from the repository.

`GET [base]/Subscription/[subscription-id]`,

where [subscription-id] is the logical id of the existing Subscription resource.

Read Subscription Response

The server returns a 200 OK HTTP status code.

The server returns a 200 OK HTTP status code, and also returns a copy the Subscription resourse in the HTTP body.

Example of Get Subscription Interaction

Example Read Request

HTTP Method:

GET

Headers:

Content-Type: application/fhir+json

Address:

[base]/Subscription/f63b8b72-23b4-4c3f-8a07-8fbe93d46f9d

Example Read Response Body

HTTP Body contains a FHIR R5 Backport Subscription resource, conformant to Profile: Subscription


{
    "resourceType": "Subscription",
    "id": "f63b8b72-23b4-4c3f-8a07-8fbe93d46f9d",
    "identifier": [
            {
            "system": "https://oh-subscriptions.ca/ids",
            "value": "subscription-12345"
            }
        ],    
    "meta": {
        "profile":  [
            "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
        ]
    },
    "text": {
        "status": "generated",
        --- We have skipped the narrative for better readability of the resource ---
    },
    "status": "active",
    "end": "2020-12-31T12:00:00Z",
    "reason": "R4/B Example Topic-Based Subscription for Patient Admission",
    "criteria": "http://hl7.org/SubscriptionTopic/admission",
    "_criteria": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
                "valueString": "Encounter?patient=Patient/123"
            }
        ]
    },
    "channel": {
        "extension":  [
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
                "valueUnsignedInt": 86400
            },
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
                "valueUnsignedInt": 60
            },
            {
                "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
                "valuePositiveInt": 20
            }
        ],
        "type": "rest-hook",
        "endpoint": "https://example.org/Endpoints/d7dcc004-808d-452b-8030-3a3a13cd871d",
        "payload": "application/fhir+json",
        "_payload": {
            "extension":  [
                {
                    "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
                    "valueCode": "id-only"
                }
            ]
        }
    }
}

Expected Behaviour

Case Scenario Description HTTP Status Code Response Payload
1 An existing Subscription is retrieved from the repository HTTP 200 Retrieved
2 The requested Subscription based on the provided logical id does not exist HTTP 404 Resource not found. Returns an OperationOutcome resource indicating an issue.
3 Subscription API validates the request but cannot return a valid response due to internal issues. HTTP 500 Internal Server Error. Returns an OperationOutcome resource indicating an issue.