REST API Concepts

This section introduces REST API concepts underlying the HMG/HSG REST API.

Required Authorization

The REST API requires user authentication. Execute the Initiate Session command to start an API session, using the login/password of the appropriate user role as described in HMG/HSG Concepts.

Each API command listed in REST API Reference includes an "Authorizations" heading that lists the user role necessary to execute the command. If you make an API call with a user role that is not authorized to execute the command, the following response is returned:

{
 "error": {
  "type": "SessionAuthorization",
  "message": "Operation not authorized for roles: [User role]"
 }
}

where User role is role of the current session's user.

Default Success HTTP Status Code

Unless otherwise specified, the standard response for successful HTTP requests is 200 OK.

JSON Properties

JSON properties are either optional, required, immutable, or ignored. The definitions are as follows:

Property	Description
Optional	If the property is not provided on a PUT or POST, the server uses the default value for PUT requests or the current value stored on the server for POST.
Required	If the property is not provided on a PUT or POST, an error is returned stating that the property must be provided.
Ignored	Ignored properties are informational only in responses and are ignored for PUT and POST requests.
Immutable	Immutable properties cannot be changed. If a PUT or POST request attempts to change or assign an immutable property, an error is returned.

HTTP Request Headers

On a POST or PUT request, the content type request header should be one of the content types supported for that specific API endpoint, either:

application/json
application/octet-stream
multipart/form-data

If the content type is different, the HTTP error 415 Unsupported Media Type is returned.

Errors

In case of an error on an API call, the API returns a response with the appropriate HTTP status code and an error message encapsulated in the body:

{
 "error": { 
  "type": "[string]",
  "message": "[string]"
 }
}