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

In addition, Table 3 defines how to construct the physical name of an element from the business name.

* Note that Element Names MUST be in camel case except for Schema Object names which MUST be in Pascal case. All element name MUST have AIDM abbreviations applied in order of length starting with the longest. For example, if there is an abbreviation of PO for Post Office and an abbreviation of PST for Post, if you apply PST abbreviation first, the outcome will be PST Office, whereas applying the longest phrase to be substituted will result in the outcome of PO; which is the desired result. In addition, the name of a structured SUP attributes must have the period punctuation mark (.), used as a grouping mechanism, removed.

An objective of this standard is the validation of the data content of instances of OAS Documents. Keywords, as well as data structure, are used to address this objective. Table 4 identifies the allowable keywords for validating the content of data and the cardinality of arrays.

2.4.14.2 Primitive Data Types

In the AIDM a Content Component and a Supplementary Component may be classified by an enumeration or by a primitive data type. If an attribute is classified by an enumeration the Primitive Data Type can be found in a tagged value called “restrictedPrimitive”; otherwise the classifier is the primitive data type. In either case the primitive data type must be transformed into a platform dependent data type as defined in Table 5 below.

Example 8 - Schema object

2.4.14.3 Traceability

No traceability from AIDM to API data elements is demanded. In future the keyword “$comments” may be used to describe the derivation of a data element from the AIDM. Including but not limited to the node path and name of the diagram used to generate the data structure and the date and time it was generated, and the navigation path and GUID of the source data element.

2.4.14.4 Error Structure

IATA standard API SHOULD use the below general error object structure within the Component Object to handle the general error message as part of an API response. 

Example 9 - Error Structure

2.4.15 Security Scheme Object

The Security Scheme Object defines a security scheme that can be used by the operations.

In IATA standard API specification:

1. APIs SHOULD apply OAuth 2.0 as security mechanism.

2. APIs SHOULD apply OWASP best practices. Additional information can be found at www.owasp.org. 

3. Appendix

3.1. Airline Value Chain

Figure 5 below shows a chain of primary activities and their process areas that a firm is operating in the airline industry performs in order to deliver a valuable product or service to the market.

Open

Figure 5 - Airline Value Chain Reference Model

Customer Touch-Point Capabilities

Business capabilities needed to deliver the core product to the customer. Organized by the lifecycle of product delivery.

Operations

Business capabilities needed to enable the running of “passenger airline” business. Organized by typical business planning cycle.

Support & Management

Business capabilities needed to enable the running of “any” business.

3.1.1 Artifacts

Artifact	Description
Business Primary Activity  Open	Entry point of the Business Activities
Business Support Capability  Open	It describes Business Processes capability details for a specific business purpose.

3.1.2 Business capability Mapping

The provider should identify the relevant Business Support Capabilities of the API, and specify those capabilities in the Tag Object of the OAS specification.  It helps  the API consumers to better understand the business purpose and benefits of the API. 

3.2. Versioning

This main purpose of this section is to describe the API versioning guideline and best practice. To cover the basic context, it also gives an overview of IATA release, deliverables in the release package and versioning guidelines of each artifact.

3.2.1 Release Overview

An IATA Release is the fact to package and publish IATA Standards deliverables at the planned schedule. For example, standard XML schemas generated from the AIDM; OpenAPI specification of standard APIs; export of complete AIDM model are grouped in one package, after ATSB adoption, etc.

The release number identifies each IATA Release. The format of release number is “IATAYYYY.S”, with “YYYY” as the year and “S” as release sequence within the year. Example of release number: IATA2018.1 - the first Release in year 2018, called also 18.1.

Figure 6 Release Overview describe the present and planned deliverables within an IATA release package, the version example of each deliverable, and where the versioning guideline for that deliverable is defined.

Open

Figure 6 Release Overview

3.2.2 Release Deliverable Versioning

3.2.2.1 AIDM entity (ABIE) version

There is version property of ABIE (Aggregated Business Information Entity) in AIDM data model. The ABIE version property is not used as of today, and it is always set as 1.0 by default. Refer to “5.3 ABIE properties” in “AIDM Guidelines - I3 Info Logical Model v2.2.docx” as part of Ref 7 - AIDM Guidelines.

Open Air group recommends to defining ABIE version in AIDM, to track the evolution of the entities.

3.2.2.2 XML Schema version

Each standard XML schema has its own version defined. The guideline of XML schema versioning is defined in the section “11 Versioning and schema identification” of “IATA XML Best Practice Document ver1.6.1.doc” as part of Ref 7 - AIDM Guidelines.

3.2.2.3 API versioning guideline

Each Standard API MUST has its own version defined in the OAS spec, to track the evolution of the API.

The major version of API MUST be included in either Server.url field or Paths Object in the OAS spec. The major version MUST be consistent for all endpoints in one API spec.

The developer SHOULD NOT use different versions of same JSON schema in one API spec.

Table 7 -  API versioning describes the versioning guideline, focused on evolution of major and minor version (as defined in Semantic Versioning 2.0.0) in the OAS spec. An API is Backwards Compatible when a client program written to consume the last version of that API will continue to work the same way against its current version.