MHNexus Sdn Bhd
0.1.0 - ci-build

API Guide

MY Core conforms to the base FHIR API framework which is described as a set of operations (known as "interactions") on resources where individual resource instances are managed in collections by their type. This section will further elaborate the operations.

This section will give an overview and basic guide for FHIR API interaction.

VERB [base]/[type]/[id]

  • VERB corresponds to the HTTP verb used for the interaction
  • Content surrounded by [] is mandatory, and will be replaced by the string literal identified. Possible insertion values:
    • base: The Service Base URL
    • type: The name of a resource type (e.g. "Patient")
    • id: The Logical Id of a resource
    • vid: The Version Id of a resource
    • param: URL parameters as defined for the particular interaction

For further details, the base FHIR documentation can be found at FHIR RESTful API.

Authentication

To access to HIE MY Core FHIR API, source system will be given credentials directly during integration discussion.

Each credential will have differing access rights to MY Core API based on the integration scope.

HTTP Method

Hypertext Transfer Protocol (HTTP) defines a set of request methods to indicate the desired action to be performed for a given resource

Below are the common HTTP method used when intereacting with HIE server:

Method Definition
CREATE Asks the server to create a new record.
READ Asks the server to retrieve a record.
UPDATE Asks the server to edit/update an existing record.
DELETE Asks the server to delete a record.

HTTP status response

HIE server will issue a response for each request as accordance to Hypertext Transfer Protocol (HTTP) standard.

All response status codes are separated into five classes or categories. The first digit of the status code defines the class of response, while the last two digits do not have any classifying or categorization role. There are five classes defined by the standard:

  • 1xx informational response – the request was received, continuing process.
  • 2xx successful – the request was successfully received, understood, and accepted.
  • 3xx redirection – further action needs to be taken in order to complete the request.
  • 4xx client error – the request contains bad syntax or cannot be fulfilled.
  • 5xx server error – the server failed to fulfil an apparently valid request.

Below are the common response status encountered when intereacting with HIE server. For further details can refer the Hypertext Transfer Protocol (HTTP) standard:

Status Definition
200 OK Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
201 Created The request has been fulfilled, resulting in the creation of a new resource.
202 Accepted The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon and may be disallowed when processing occurs.
204 No Content The server successfully processed the request and is not returning any content.
206 Partial Content The server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads or split a download into multiple simultaneous streams.
400 Bad Request The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401 Unauthorized Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. See Basic access authentication and Digest access authentication. 401 semantically means "unauthorised", the user does not have valid authentication credentials for the target resource.
403 Forbidden The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort or attempting a prohibited action (e.g. creating a duplicate record where only one is allowed). This code is also typically used if the request provided authentication by answering the WWW-Authenticate header field challenge, but the server did not accept that authentication. The request should not be repeated.
404 Not Found The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
405 Method Not Allowed A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
409 Conflict Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
413 Payload Too Large The request is larger than the server is willing or able to process. Previously called "Request Entity Too Large" in RFC 2616.
415 Unsupported Media Type The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
422 Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors.
429 Too Many Requests The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
500 Internal Server Error A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503 Service Unavailable The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.
504 Gateway Timeout The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
511 Network Authentication Required The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network (e.g., "captive portals" used to require agreement to Terms of Service before granting full Internet access via a Wi-Fi hotspot).

CREATE

The create interaction creates a new resource in a server-assigned location. The create interaction is performed by an HTTP POST command as shown:

POST [base]/[type]

The request body SHALL be a FHIR Resource of the named type. The resource does not need to have an id element (this is one of the few cases where a resource exists without an id element). If an id is provided, the server SHALL ignore it. If the request body includes a meta, the server SHALL ignore the existing versionId and lastUpdated values. The server SHALL populate the id, meta.versionId and meta.lastUpdated with the new correct values.

Example
POST https://fhir.hie.moh.gov.my/baseR4/Patient

If a source system requires to have control over the id of a newly submitted resource, it should use the update interaction instead.

READ

The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET command as shown:

GET [base]/[type]/[id]

This returns a single instance with the content specified for the resource type. This url may be accessed by a browser. The possible values for the Logical Id ("id") itself are described in the id type. The returned resource SHALL have an id element with a value that is the [id].

Note: Unknown resources and DELETE resources are treated differently on a read: a GET for a DELETE resource returns a 410 Gone status code (see the delete interaction for addition details), whereas a GET for an unknown resource returns 404 Not Found.

Example
GET https://fhir.hie.moh.gov.my/baseR4/Patient/aaa37a64-929c-4a29-9b5b-6c257a554728

Source System may perform searches via HTTP GET by making an HTTP GET request to the appropriate context, with search parameters included as HTTP Query Parameters.

GET [base]/[resource-type]?param1=value&...

If the search succeeds, the server SHALL return a 200 OK HTTP status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero or more resources in a defined order.

Example 1
GET https://fhir.hie.moh.gov.my/baseR4/Patient?identifier=910503145678
Example 2
GET https://fhir.hie.moh.gov.my/baseR4/Patient?identifier=910503145678&name=NURUL

VREAD

The vread interaction performs a version specific read of the resource. The interaction is performed by an HTTP GET command as shown:

GET [base]/[type]/[id]/_history/[vid]

This returns a single instance with the content specified for the resource type for that version of the resource. The returned resource SHALL have an id element with a value that is the[id], and a meta.versionId element with a value of [vid].

The Version Id ("vid") is an opaque identifier that conforms to the same format requirements as a Logical Id. The version Id may have been found by performing a history interaction (see below), by recording the version id from a content location returned from a read or from a version specific reference in a content model. If the version referred to is actually one where the resource was DELETE, the server should return a 410 Gone status code (see the delete interaction for addition details).

Example
GET https://fhir.hie.moh.gov.my/baseR4/Patient/aaa37a64-929c-4a29-9b5b-6c257a554728/_history/1

UPDATE

The update interaction creates a new current version for an existing Resource or creates an initial version if no resource already exists for the given id. The update interaction is performed by an HTTP PUT command as shown:

PUT [base]/[type]/[id]

The request body SHALL be a Resource of the named type with an id element that has an identical value to the [id] in the URL. If no id element is provided, or the id disagrees with the id in the URL, the server SHALL respond with an HTTP 400 Bad Request error code, and SHOULD provide an OperationOutcome identifying the issue. If the request body includes a meta, the server SHALL ignore the provided versionId and lastUpdated values. If the server supports versions, it SHALL populate the meta.versionId and meta.lastUpdated with the new correct values.

Note that update generally updates the whole content of the resource.

If the interaction is successful and the resource was updated, the server SHALL return a 200 OK HTTP status code. If the interaction is successful and the resource was created, the server SHALL return a 201 Created HTTP status code.

Example
PUT https://fhir.hie.moh.gov.my/baseR4/Patient/aaa37a64-929c-4a29-9b5b-6c257a554728

HIE server will reject update interactions if there are integrity concerns or other business rules issues, and return HTTP status codes accordingly (usually a 422).

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

  • 400 Bad Request - resource could not be parsed or failed basic FHIR validation rules (or multiple matches were found for conditional criteria)
  • 401 Not Authorized - authorization is required for the interaction that was attempted
  • 404 Not Found - resource type not supported, or not a FHIR end-point
  • 405 Method Not allowed - the resource did not exist prior to the update, and the server does not allow client defined ids
  • 409/412 - version conflict management - see below
  • 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules

These error SHOULD be accompanied by an OperationOutcome resource providing additional detail concerning the issue. In general, if an instance fails the constraints documented in the CapabilityStatement then the response should be a 400, whereas if the instance fails other non-externally described business rules, the response would be a 422 error. In practice, HIE servers may also return 5xx errors in these cases without being deemed non-conformant.

UPDATE AS CREATE

The server allows a source system to PUT a resource to a location that does not yet exist on the server - effectively, allowing the source system to define the id of the resource.

PUT [base]/[type]/[id]

This API method accommodate scenarios where;

  • a source system is reproducing a new record on the server, and needs to keep original ids in order to retain ongoing integrity
  • source system is a server doing push-based pub/sub (this is a special case of the first reason
  • multiple source systems doing push in the context of agreed data model shared across multiple servers where ids are shared across servers

The server SHALL not return a 201 response if it did not create a new resource. If a new resource is created, a location header SHALL be returned (though it SHALL be the same as the location in the URL of the PUT request).

Example
PUT https://fhir.hie.moh.gov.my/baseR4/Patient/aaa37a64-929c-4a29-9b5b-6c257a554728

DELETE

The DELETE interaction removes an existing resource. The interaction is performed by an HTTP DELETE command as shown:

DELETE [base]/[type]/[id]

The request body SHALL be empty. A delete interaction means that the resource can no longer be found through a search interaction. Subsequent non-version specific reads of the resource return a 410 Gone HTTP status code when the server wishes to indicate that the resource is DELETE. Upon successful deletion, or if the resource does not exist at all, the server should return either a 200 OK if the response contains a payload, or a 204 No Content with no response payload.

Delete function is by default disable for other source sytem integrating with HIE. If record deletion is required, it must go through case-by-case basis.

Example
DELETE https://fhir.hie.moh.gov.my/baseR4/Patient/aaa37a64-929c-4a29-9b5b-6c257a554728

BATCH/TRANSACTION

The batch and transaction interactions submit a set of actions to perform on a server in a single HTTP request/response. The actions may be performed independently as a "batch", or as a single atomic "transaction" where the entire set of changes succeed or fail as a single entity. Multiple actions on multiple resources of the same or different types may be submitted, and they may be a mix of other interactions defined on this page (e.g. GET, POST, PUT, DELETE) command as shown:

POST [base]

A batch or transaction interaction is performed by an HTTP POST command as shown:

Example
POST https://fhir.hie.moh.gov.my/baseR4

The content of the POST submission is a Bundle with Bundle.type = batch or transaction. Each entry SHALL carry request details (Bundle.entry.request) that provides the HTTP details of the action in order to inform the system processing the batch or transaction on what to do for the entry.