Using the API

Pagination

When making an API request, you usually don't receive all of the results of that request in a single response. This is because some responses could contain thousands of objects so most responses are paginated by default.

Cursor-based Pagination

Cursor-based pagination is the most efficient method of paging and should always be used when possible. A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn't store cursors or assume that they will be valid in the future.

When reading an edge that supports cursor pagination, you see the the following JSON responses:

Flight Info API:

{ 
   "data": [ ... data ],
   "paging": {
      "limit": 1,
      "totalCount": 23,
      "totalPages": 23,
      "next": "https://api.oag.com/flight-instances?DepartureDate=2022-05-28&Limit=1&version=1.0&After=202205280705-1669289217243000000-b302d3f0437c9c10c8520a968972d9a7dab639bc079dea288ff5bc5b2bce94e7"
   }
}

Schedules:

{ 
   "data": [ ... data ],
   "paging": {
      "limit": 1,
      "totalCount": 23,
      "totalPages": 23,
      "previous": "https://api.oag.com/flights?departuredate=2023-03-09&limit=1&cursor=0000082f78fdff8d22aaab49015bacf6a4ab0a61fe8d202096175f4d8b71fe7a",
      "next": "https://api.oag.com/flights?departuredate=2023-03-09&limit=1&cursor=00010cd3690b0d84f46bce2e48bdbaaa3ea517da2f7c96f33ed2fd7de1b8eb44"
   }
}

A cursor-paginated edge supports the following parameters:

• limit : This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering.

• totalCount : This is the total amount of records returned by the query.

• totalPages : This is the total amount of pages returned by the query.

• previous*: The API endpoint that will return the previous page of data.

• next : The API endpoint that will return the next page of data. If not included, this is the last page of data. Stop paging when the next link no longer appears.

*Only returned for Schedules API.

Health Check API

The Health APIs are public endpoints that give information on each service's health.

Request

The following are examples of requests to Health Check API:

GET /flights/health

GET /schedules/health

GET /master-data/health

Response

Depending on the service health status the following responses can be returned:

• HTTP Status 200 OK

• HTTP Status 503 Service Unavailable

Sample 200 OK response (Flight Info API):

{
 "flightInfo": "healthy"
}

Sample 503 Service Unavailable response (Schedules API):

{
 "schedules": "unhealthy"
}

Cross-Origin Resource Sharing (CORS)

Cross-Origin Resource Sharing (CORS) is generally not allowed in most APIs and web services due to security concerns. This includes the APIs provided by OAG. To integrate the API, it’s recommended to use a server-side approach. Enabling CORS on the front-end could expose your subscription key to the public and allow others to misuse it.

API version life cycle

After the launch of a subsequent version, a version will be retired approximately one year later. For instance, if API version v2 is released on April 30th, 2023, v1 will be decommissioned on May 1st, 2024. It is important to note that a version will be flagged as deprecated once the next version is released.

A deprecated API version will start returning two new headers: "Deprecation" and "Sunset" with the date when the API will no longer be available.

deprecation: true
sunset: 2024-05-01

Knowledge Base

Have a question? The OAG knowledge base is full of frequently asked questions, how-to guides, and product documentation, designed to make it quick and easy for you to access information, regarding integrating and using the OAG APIs. You can access our Knowledge Base here.