API Convention

API Definitions

Whenever the spelling for a particular entity is ambiguous between different lects of English, always side with American English.

There are two distinct base URLs for the solution.

  • Traveler - This represents all resources and actions that an end user of the SDK would need. Functionality such as browsing a catalog, making orders or viewing flights.

  • Partner - This represents global company level tooling that an administrator of an SDK implementation may need. The Management Console provides a user interface for this, however sometimes it's useful to be able to programatically administer the tool via the API directly.

API Convention

Resources

  • Resources should always be singular, and should descend into its components down a path. e.g

    https://guestlogix.io/resource/{resource-id}/sub-resource/{sub-resource-id}
  • Query parameters are to use lowercase 'spinal' or 'kebab' case. e.g.

    https://guestlogix.io/resource?query-param=x&another-query-param=y

API Errors

Should the API consumer provide insufficient parameters, or request a resource out of order the API will return a 4xx level status code. For more granularity, an error code and message will accompany the response. The errors are outlined in more detail in the Error Codes.

Date and Time Formatting

In the context of JSON formatting, the following methods of representation are used:

DateTime

When an instance in time is needed, a fully formatted ISO 8601 string is to be used.

eg.

{
"dateTime" : "2018-12-10T17:05:09Z" //December 10th 2018 12:05:09pm UTC Time
}

Date

When a single calendar day is needed to be represented, and time is irrelevant, a string of the format YYYY-MM-DD is to be used.

eg.

{
"date" : "2018-12-10" //December 10th 2018
}

Time

When a time of day is to be used, the attribute that holds it should have the suffix inSeconds, inMinutes or inHours etc. and refers to corresponding integer number since midnight of a given day.

eg.

{
"timeInSeconds" : 25200, //7:00am
"timeInMinutes": 420, //7:00am
"timeInHours": 7 //7:00am
}