Environment Setup

Swagger

No application install is required for this tool.

Using Swagger

1. Launch Swagger
2. Click the Authorize button to authenticate with Okta:
   
3. Provider your 3rd party integrator client_id (0oar9yhskte3BGIk20h7) and check the “apiscope” check box, then click “Authorize”.
   
4. You will be redirected to Okta where you will need to provide your Okta login credentials (which will be the same as your AirPortal credentials).
   
5. After you have successfully authenticated, click the “Close” button and you will be able to submit requests against the API via the Swagger UI
   
   

Postman

Download Postman here and run the installation package.

Using Postman – Import REST API definitions

1. Launch Postman and click the Import button in the upper left-hand corner then choose the “Link” tab.
   
2. Enter the Swagger JSON definition for the REST APIs in the URL text box and click “Continue”.
   /swagger/v1/swagger.json
3. On the subsequent screen, uncheck “API” and click “Import” to finalize the import process.
   

Using Postman – Configure Environment

1. Start by clicking the “Manage Environments” gear in the upper right-hand corner and clicking the “Add” button on the resulting dialog.
   
2. On the resulting screen, give the environment a name, add the following variables and click “Add”.
   
   • baseUrl: https://api-staging.cbtat.com
   • oktaBaseUrl: https://id-staging.cbtat.com/
   • oktaAuthorizationServer: ausr7tcnbxuFgDYYa0h7
   • oktaClientId: 0oar9yhskte3BGIk20h7
   • oktaState: testing
   • oktaNonce: nonce
   • oktaScope: apiscope
   • postmanRedirectUri: https://www.getpostman.com/oauth2/callback

   Note: The above variables will be used for OAuth 2 interaction with Okta when using Postman to submit tests against the REST APIs.

Using Postman – Authenticate and Submit a Request

1. Choose the “/v1/booking/cn-{confirmationNumber}” endpoint from the collection that was imported in Section 2.2.1, enter a valid record locator and set the depth to “Infinite”.
   
2. Click the “Authorization” tab, choose “OAuth 2.0” from the “Type” drop down, select “Request Headers” from the “Add authorization data to” drop down and click the “Get New Access Token” button.
   
3. Enter the following values in the dialog and click “Request Token” to be redirected to an Okta authenticate page, then enter your Okta credentials and login.
   
   • Token Name: accessToken
   • Grant Type: Implicit
   • Callback URL:
   • Auth URL: /oauth2//v1/authorize?nonce=
   • Client ID:
   • Scope:
   • State:
   • Client Authentication: Send as Basic Auth header
4. After successful Okta authentication, you will be redirected to the following screen. Click “Use Token” and your request will now be ready to send
   
5. Click the Send button to send the authenticated request to the REST API and get the results.
   

Available Endpoints

Booking

Booking related endpoints are used to search for and retrieve bookings via the REST API. See the Swagger definition for the various Booking endpoints for more details on parameters and return types.

Find

• Endpoint: /v1/bookings (POST)
• Description: The Booking Find endpoint is used to search for bookings and return high level information about those bookings.  Basic search criteria include creation date, departure date, passenger id, passenger name, booking status, etc.
• Behaviour Notes: Both Travelers and Travel Managers can use this functionality. However, they will only be able to see bookings that reside within the same “client” as the user account they logged in with.

Get (confirmationNumber)

• Endpoint: /v1/booking/cn-{confirmationNumber} (GET)
• Description: The Booking Get endpoint is used to retrieve a single booking by confirmation number (record locator) and return its detailed information.
• Behaviour Notes: Both Travelers and Travel Managers can use this functionality. However, they will only be able to retrieve bookings that reside within the same “client” as the user account they logged in with.

Get (bookingId)

• Endpoint: /v1/booking/{bookingId} (GET)
• Description: The Booking Get endpoint is used to retrieve a single booking by booking id and return its detailed information.
• Behaviour Notes: This “Get” endpoint will exceed the performance of “Get” by confirmation number, so it should be used where possible (booking id is returned from Find). 

  Both Travelers and Travel Managers can use this functionality. However, they will only be able to retrieve bookings that reside within the same “client” as the user account they logged in with.

User

User related endpoints are used to get details about a specific user via the REST API. See the Swagger definition for the various User endpoints for more details on parameters and return types.

Get

• Endpoint: /v1/user/{userId} (GET)
• Description: The User Get endpoint is used to retrieve a single user by its unique id and return its detailed information.

Behaviour Notes: Both Travelers and Travel Managers can use this functionality. However, they will only be able to retrieve details about the user associated with the account they logged in with.

Get (username)

• Endpoint: /v1/user/un-{username} (GET)
• Description: The User Get endpoint is used to retrieve a single user by any of its unique usernames and return its detailed information.
• Behaviour Notes: Only Travel Managers can use this functionality. Additionally, they will only be able to retrieve details about a user who is associated with the same client as the user account they logged in with.

Client

Client related endpoints are used to get details about a specific client via the REST API. See the Swagger definition for the various Client endpoints for more details on parameters and return types.

Get

• Endpoint: /v1/client/{clientId} (GET)
• Description: The Client Get endpoint is used to retrieve a single client by its unique id and return its detailed information.
• Behaviour Notes: Only Travel Managers can use this functionality. Additionally, they will only be able to retrieve details about the client associated with the user account they logged in with.

Workflow

Error Conditions

500 – Internal Server Error

If any error is encountered while using the REST APIs, you will receive an http status code of 500 as well as a JSON response body in the following format:

You can rely on this http status code and JSON format when handling error conditions.

Here is a brief description of the JSON response:

• exceptionLevel.code: The code representing the category of error that occurred.
• exceptionLevel.description: The description of the category of error that occurred.
• uniqueID: An identifier that is used by CBT to trace the source of the error as well as capture additional information about the user and the action they attempted to perform when the error occurred.
• message: A human readable description of the error that occurred.
• exceptionDetailList(n).key: In the case of a validation error, the key identifies the class and property of the request that did not pass validation as well as an identifier that signifies why it did not pass validation.  Examples: Required, Max, Min, etc.
• exceptionDetailList(n).property: In the case of a validation error, they property identifies the property of the request that did not pass validation.
• exceptionDetailList(n).message: In the case of a validation error, the message is a human readable description of the validation error that occurred.

401 – Unauthorized

If you have attempted to access the REST APIs without first authenticating with Okta, you will receive a 401 Unauthorized error and the following response headers:

404 – Not Found, 204 – No Content, etc.

• While not actual error conditions, these http status codes will be returned from the REST APIs when performing specific actions as defined by REST and/or Web Resource standards.
• Examples:
• 404 – Not Found (Get)
• 201 – Created (Add)
• 204 – No Content (Update, Delete)