# API Convention

### API Definitions

{% hint style="info" %}
Whenever the spelling for a particular entity is ambiguous between different [lects](https://en.wikipedia.org/wiki/Variety_\(linguistics\)) of English, always side with [American English](https://en.wikipedia.org/wiki/American_English).
{% endhint %}

There are two distinct base URLs for the solution.

* [Traveler](https://docs.guestlogix.io/traveler/api) - 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 ](https://docs.guestlogix.io/partner/api)- 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](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles). 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](https://docs.guestlogix.io/glossary/api-convention/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](https://en.wikipedia.org/wiki/ISO_8601) string is to be used.

eg.

```javascript
{
   "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.

```javascript
{ 
   "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.

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