Revision History 

1.1. Purpose

IATA’s Open Air initiative was created to develop industry standards and best practices for the use of RESTful API technology in the airline industry, and an API ecosystem conformant to the standards.

The purpose of this document is to define a common technical approach to describing API Definitions so that industry parties can benefit from a shared understanding leading to efficiency of API development, understanding, implementation and use of conformant APIs.

1.2. Audience

This standard assumes the reader has an understanding of the OAS 3.0 specification, and AIDM methodology. This document is intended for:

·         API developers in the airline industry, who have experience in RESTful API design and development;

·         Enterprise Architects responsible for the coherent strategies of their companies’ integration policies;

·         Planners and Managers responsible for delivering business integration solutions.

1.3. Document Structure

The document covers each OAS Object and its fields or patterned fields where there is a variation with the OAS Standard, or where the Object is required but no variation is defined. The OAS nodes affected by this standard are shown in Figure 1 – Open API Standards Scope.

Variances in the standard for an Object that appears in more than one place, that is, more than one node in the OAS specification are detailed in a sub-section of the section covering the Object.

The sections detailing each object are ordered as they appear in the OAS Standard.

2. Open Air API Standard

2.1. Objective

The objective of this standard is to ensure API Documents are consistent in their structure, nomenclature and semantics and to enable the data structures in conformant messages to be validated; JSON Schema keywords for validation are utilized to achieve this.

2.2. Interpretation

When describing the Best Practices and the Checklist, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2.3. Standard APIs

There are 2 types of standard APIs supported in the Open Air program.

1. Compliant API

2. Conformant API

2.3.1 Compliant – Proprietary API

IATA recommends the API providers to follow the industry adopted Open Air API Standards and Best Practices in the proprietary API. The provider may design and develop the proprietary API to address any business scenario in support of any stages or any steps across the Airline Value Chain, which is shown in Figure 5.

An airline industry relevant API provider, who follows the standards and successfully delivers the API, may apply for Open Air compliance certification for the proprietary API. The certified API is recognized as a Compliant API and is listed in the Open Air Industry API Registry, providing visibility to the industry.

2.3.2 Conformant – Industry Standard API

A Conformant API is an API designed by the industry standard development bodies, for example, the business and technology working groups and boards under IATA PSC governance, to address a common business scenario faced by most of the applicable industry parties. The business scenario can be from any stages or steps across the Airline Value Chain capabilities shown in Figure 5.

A Conformant API specification MUST adhere to the Open Air standard and Best Practices. The delivery of IATA Conformant APIs MUST follow industry governance process under the Passenger Standards Conference (PSC). The business process and requirement MUST be adopted by corresponding business boards, for example, Plan Board, Shop-Order Board, Pay-Account Board, Travel Board, etc, and the API specification, as well as data model MUST be adopted by Architecture and Technology Strategy Board (ATSB).

2.4. API specification

This section defines the Open Air Standard and Best Practice for API specification. API specification is a reference manual on the API capability, meaning how the API behaves and what to expect from the API. A well-documented specification will help developers to understand and adopt the API.

An IATA Open Air API document MUST be RESTful, MUST adhere to OAS 3.0 standard, and MUST use HTTPS protocol. All data structures MUST be defined using JSON Schema with modifications as defined in the OAS 3.0 standard. Each Open Air API document MUST be available in JSON format, and MAY in addition be available in YAML format.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs. The Open Air Standard leverages OAS 3.0 and covers the usage of the OAS 3.0 objects and fields shown in Figure 1 below. This document does not intend to describe the usage of all required or optional OAS objects and related fields. Any API defined using the Open Air Standard MAY make use of any other objects and fields of the OAS 3.0 Standard, but any such usage MUST NOT affect the meaning or behaviour of the objects and fields covered by this standard.

Open

Figure 1 - Open API Standards Scope

2.4.1 OpenAPI Object

OpenAPI Object is the root document object of the OAS 3.0 specification.

In IATA standard API specification, the value of openapi attribute MUST be 3.0 or a minor version there-of. It means the API specification is documented using Open API Specification 3.0.

2.4.2 Info Object

Info Object provides metadata about the API.

Each specification (OAS) MUST have its own version. Version notation MUST follow Semantic Versioning 2.0.0.  Section 3.2 describes the  versioning best practice.

Example 2

2.4.3 URI

A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies a resource.  URI Internet Standard Specification is defined in RFC3986.

As resource oriented design approach, it is critical to define a meaningful URI for the resource, in order to help developers to understand and use the RESTful API.

Figure 2 – URI components below is the example that shows the components in the URI.

Open

Figure 2 – URI components

The standard and best practice on URI is defined in 2.4.4 Server Object and 2.4.6 Paths Object.

2.4.4 Server Object

Servers Object include an array of Server Objects. The Server Object provides connectivity information to a target server.

2.4.4.1 URL

To keep the consistency of URL formatting:

1. URL SHOULD follow URI specification RFC3986.

2. URL SHOULD define the scheme and authority components of URI specification.

3. All characters in URL SHOULD be in lowercase.

4. A hyphen (-) MUST be used in URL to separate multi-word phrases, except that the parameter name MUST follow camel case as naming convention as described in section 2.4.9 Parameter Object.

5. File extensions MUST NOT be included in the server URL.

Description field MUST be defined for each Server Object structure.

Example 5 - Server Object

2.4.5 Components Object

Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

There are no variations to the OAS Standard defined for this object.

2.4.6.1 Resource Naming

In REST, primary data representation is called Resource. Generally, a resource is a thing not an action and is identified by a noun. HTTP Verbs MUST be used to define the action to be performed on the Resource.

Table 1 categories resources and defines the nature of the resource name for each category.

Figure 3 - Resource naming structure shows the general pattern of a Resource Name being:

Open

Figure 3 - Resource naming structure

In order to keep the consistency in Resource Naming:

1. The Root and Child Resource Name MUST be the names of ABIEs or ASBIE Roles optionally preceded with a Status separated by a forward slash (“/”).

2. Resource name SHOULD be identified by a noun, unless the archetype is Controller.

3. Resource name MUST be plural unless it is a singleton resource in which case a singular noun MUST be used.

4. The Child Resource UID MUST be the unique identifier components of the ABIE separated by a hyphen.

5. The hierarchical structure of a Resource Name MUST be constructed by traversing through the Integrated Data Model in the AIDM moving from an ABIE (Resource) to a child ABIE (Resource) via an ASBIE (Hierarchical Link).

6. Controller Resource name MAY be a verb, and MAY be a verb with a suffix, for example "-jobs", so that the resource could be accessed via proper UID, for example job ID.

2.4.7 Paths Item Object

Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

There are no variations to the OAS Standard defined for this object.

2.4.8 Operation Object

Operation Object defines the HTTP methods can be used to access a path. A unique operation is a combination of a path and an HTTP method. A single path can support multiple operations.

OAS 3.0 supports HTTP methods of get, post, put, patch, delete, head, options, and trace. In Operation Objects, the specification MUST follow all HTTP methods definition and guidance in RFC7231.

2.4.9 Parameter Object

Parameter Object describes a single operation parameter. A unique parameter is defined by a combination of a name and location.

There are four possible parameter locations specified by the “in” field:

1. path - Used together with Path Templating, where the parameter value is actually part of the operation's URL. The path parameter is required in all cases to access the API.

2. query - Parameters that are appended to the URL. e.g /users?role=admin

3. header - Custom headers that are expected as part of the request. Refer to RFC7230 for more information

4. cookie - Used to pass a specific cookie value to the API. Refer to RFC6265 for more information

Path parameter SHOULD be used to identify a specific resource via UID, e.g get /users/{id}.

Query parameter SHOULD be used to filter or sort the sources.

The parameter name MUST follow camel case as naming convention.

2.4.10 Request Body Object

The Request Body Object describes a single request body, which is used to send data via REST API.

A Request Body SHOULD be used to send resource information, that is, content, in order to create or update the resource, in POST or PUT operations respectively.

2.4.11 Responses Object

A container for the expected responses of an operation. The container maps a HTTP response code to the expected response.

There are no variations to the OAS Standard defined for this object.

2.4.12 Response Object

Response Object describes an expected response of an operation. A response is defined by its HTTP status code and the data returned in the response body and/or headers.

In IATA standard API specification:

1. Response MUST be defined for HTTP status codes of 2xx (successful), 4xx (Client Error), and 5xx (Server Error). Refer to RFC7231 for the available status code and definition.

2. The media type “application/json” MUST be used by default.

2.4.13 Tag Object

The Tag Object adds metadata, including name and description, to a single tag which can be used for logical grouping of operations for the specific resource. In OpenAPI Object, the tags fields MUST be denoted to declare the list of Tag Object used in Operation Object in the specification.

In Operation Object, tags field contains a list of tag names of Tag Objects defined within OpenAPI Object. The operation.tags field MUST include a list of Airline Value Chain business capabilities key words (refer to Appendix 3.1 for more information).

For example, “Flight Status” API has “Communication Management” as Business Capability.

Example 6 – Tags

 2.4.14 Schema Object

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema published Draft 5 which includes the Core “draft-wright-json-schema-00” and the Validation “draft-wright-json-scema-validation-00”. Unless stated otherwise, the property definitions follow this standard. 

In IATA standard API specification:

1. If the data type is object, Schema object MUST be defined within Components Object, which can be referenced from other objects in the specification

2. If the data type is primitives, schema object MAY be defined in line with the parent structure

3. Regular expressions SHOULD be defined using the JSON Schema keyword “pattern”; for data validation purposes.

Example 7

4. An Examples structure MUST be defined for all schema objects in the API specification.

2.4.14.1 Schema Definition

This section defines the standard for describing reusable data structures that appear as Schema Objects within the Components section. 

The organization of data structures in this standard is similar to the Venetian Blind concept in that all object definitions are defined globally and may be reused by other objects in the Schemas section.

All data structures in IATA standard APIs MUST be derived from the AIDM, with the exception of Experimental Content.

Experimental Content is any schema data structure in an API specification, which has not been derived from the AIDM. Developers may want to extend the standard schema object to fulfill the business requirements in the proprietary API, so Experimental Content offers flexibility of extension.  Experimental Content MUST NOT appear in any Conformant API specifications (Industry Standard Open API specifications published by IATA).

Table 2 defines how to represent the data element from AIDM in an OAS schema object. All the fields in OAS Schema template described in Table 2 are mandatory, except where it is indicated otherwise.

Figure 4 is the meta-model diagram for the elements in AIDM integrated data model.

Open

Figure 4 Integrated Model Meta-Model elements