Common elements

The API has a number of elements that are common to all API endpoints.

Request

Request format

An example API call URL is shown below. The API call is to an API called ‘TestRequest’, which is in API group ‘System’.

https://irisapi.net/API/V40/System/Session/TestRequest?sessionToken=BNvbl2JD04gKAAAABAAAAAIAAAAFYWNjb3IDAAAAB1N0SmFtZXMFAAAAAi0xBAAAAANlbmcAAAAA.QoEDK5zTeBFHWVpyWFv2TuHKGdFdq3BfrOHpv37MJS8

URL Part	Description
irisapi.net	The registered domain of the customer.
/API/V40/	The version of the API that the customer is using.
System	An API group. All API calls referring to the same topic will be grouped together to make it easier to find and manage.
Session	The API Topic
TestRequest	The name of the API call to be invoked.
sessionToken	The session token is an encoded identity context that allows the API to operate in a stateless manner. It is obtained at the beginning of the session and needs to be passed with every API call.

Response

Response format

In the new API, calls will be responded to with messages that are designed to be composed of multiple parts (composite messages). An example is shown below.

{
    "sessionToken":"27F7CBB5202ED3880500000000000000000000001307CDC17A0AA1E12060602BA2CDF6FDDA95B19127F3693122116B8B9A8ECBA1", 
    "responsesIncluded": "TestResponse", 
    "responses": [
        {
            "TestResponse": {
                "content": { 
                    "Name": "John Smith", 
                    "Age": 21, 
                    "Registered": "2013-02-05T12:35:21.3286245+01:00" 
                }, 
            "succeeded": true, 
            } 
        } ],
    "status": Success, 
    "errorCode": None 
}

Property	Description
sessionToken	The session token is also returned as part of every response message and should be updated at the called end with newer versions, as it may be modified during API usage.
responsesIncluded	The responses included contains a list of the actual messages contained in the composite message, for easier filtering. Be aware, that sometimes this list can contain messages that were not requested, if the API needs to update the caller with additional information.
responses	This block contains a list of the actual response messaged. These can vary depending on the API that was called.
succeeded	A simple true/false indicator to show if the response succeeded.
errorCode (message level)	A generic indicator for any error that may have occurred during response execution. None Unauthorized Error This is not intended to be an exhaustive list, but will contain any event that effects the operational flow (for example, needing to log in).
areaErrorCode	A more detailed error code that is specific to the response.
Status	An indicator of the composite message state. Success Mixed Failure

HTTP Response Codes

Status	HTTP Status Code	Description
Success	200 OK	Basic success code. Works for the general cases. Especially used on successful first GET requests or PUT/PATCH updated content.
	201 Created	Indicates that a resource was created. Typically responding to PUT and POST requests.
	202 Accepted	Indicates that the request has been accepted for processing. Typically responding to an asynchronous processing call (for a better UX and good performances).
	204 No Content	The request succeeded but there is nothing to show. Usually sent after a successful DELETE.
	206 Partial Content	The returned resource is incomplete. Typically used with paginated resources.
Client Error	400 Bad Request	General error for a request that cannot be processed. GET /bookings?paid=true 400 Bad Request {"error":"invalid_request", "errorDescription":"There is no ‘paid’ property"}
	401 Unauthorized	I do not know you, tell me who you are and I will check your permissions. GET /bookings/42 401 Unauthorized {"error”:"no_credentials", "errorDescription":"You must be authenticated"}
	403 Forbidden	Your rights are not sufficient to access this resource. GET /bookings/42 403 Forbidden {"error":"protected_resource", "error_description":"You need sufficient rights"}
	404 Not Found	The resource you are requesting does not exist. GET /hotels/999999 404 Not Found {"error":"not_found", "error_description": "The hotel ‘999999’ does not exist"}
	405 Method Not Allowed	Either the method is not supported or relevant on this resource or the user does not have the permission. PUT /hotels/999999 405 Method Not Allowed {"error":”not_implemented", "error_description":"Hotel creation not implemented"}
	406 Not Acceptable	There is nothing to send that matches the Accept-* headers. For example, you requested a resource in XML but it is only available in JSON. GET /hotels Accept-Language: cn 406 Not Acceptable {"error": "not_acceptable", "error_description":"Available languages: en, fr"}
Server Error	500 Internal Server Error	The request seems right, but a problem occurred on the server. The client cannot do anything about that. GET /users 500 Internal server error {"error":"server_error", "error_description":"Oops! Something went wrong…"}

Response Types

Success	All of the elements of a composite message have been processed successfully
Mixed	Part of the elements of a composite message have been processed successfully
Failure	The composite message could not be processed or all elements of the composite message failed.

Response error codes

None
Unauthorized
Error

HTTP Header – Cache Control

On all GET calls, a Cache-Control header is included.

Session

API interface token

The API interface token is a token generated by the customer, using the Manager application that permits the customer to use the API. Without this token none of the API calls will work and as such this token must be passed as one of the first initialisation calls.

Initialise Session

The API v4 has one mandatory call to initialise a session called InitialiseSession. This call uses an application token configured in GXP v4 and links the session to a property, also configured in GXP v4.

To link the session to a property the caller has two options to set the property code:

Hotel property identifier. The format of this is for example, H9999.
Use the numeric value of the hotel property identifier. The format is 9999.

The initialise session will return a sessionToken if the property has been identified correctly. The sessionToken needs to be sent with every call and will be returned with every call. The sessionToken contains context about the session such as language, content version, user identification.

After successful initialisation the application can utilise all calls in the unauthorised part of the API.

Identity context

The identity context is established on the initialisation of a session. However, during the session some calls modify the identity context depending on authorisation, content version language, etc. At this point the API takes the following information in the identity context:

Element	Description
group_code	The group_code is set from the API Token and links the session to a particular group
property_code	The property_code links the session to a particular property
guest_id	The identification of the guest after being authorised.
cms_content_version	The version of the content that is retrieved from the CMS.
language_code	The language selected by the guest.

Languages

The GXP API v4 has two calls for managing languages used in the application:

Settings/Languages
This call gets all languages that have been configured for the property
Session/Language
This call will set the language for the application user and stores this in the sessionToken.

If no language has been set, the API will deliver content in the default language that was configured in GXP v4.