CRUD APIs

Healthcode provides HTTP-based APIs which follow the principles of REST. Where relevant, the APIs enable CRUD (create, read, update, and delete) operations on the data entities. Such CRUD APIs support common interface standards as specified below.

Get/Search Resources API
  • Uses HTTP method GET.
  • The API supports the list handling features as specified here.
Create Resource API
  • Uses HTTP method POST.
  • On successful creation of the resource, the API returns the instance of the persisted resource in response. Where relevant, newly generated unique id(s) are enriched within the returned resource.
Update Resource API
  • Uses HTTP method PUT.
  • On successful creation of the resource, the API returns the instance of the persisted resource in response.
Delete Resource API
  • Uses HTTP method DELETE.
  • Accepts the unique id of the resource to be deleted as a single path parameter.
  • On successful deletion of the requested resource, the API returns an instance of OperationOutcome resource with severity as information to indicate successful execution of the request.

HTTP status codes

Healthcode APIs return standard HTTP status codes to communicate the status of request processing.

  • 2xx – The response code in 200 range implies the API call has succeeded.
  • 3xx – Where an API returns either 301 or 302 status, the API will provide an alternate API endpoint in Location header parameter. The calling system must retry the API call against the alternate endpoint supplied.
  • 4xx – Status codes in the 400 range indicate an error due to invalid input, including trying to access invalid API endpoints, authentication failures and input parameter validation failures.
  • 5xx – 500 range status codes indicate the API request was valid but failed due to an unexpected issue on the server side. The calling systems may retry the original API call and should inform Healthcode if the error persists.

Note, 2xx status only indicates success of the call and not necessarily the completion of processing. In a few cases a request could successfully be accepted for processing and the caller needs to use a separate API to monitor the processing status. In such cases the initial request API will, in general, return http status 202/Accepted.