Schedaero API Basics

All API services are based on the REST architectural style and they are all stateless. All calls to the APIs require a secure HTTPS connection. Supported security protocol is TLS 1.2.

API Connections


Accessing the APIs require an active API connection.

Permissions


Each API connection has a set of permissions that restrict which operations can be called.

Company Access


Each API connection is connected to one Avinode or Schedaero member’s company account. This is used to determine which company accounts’s data the API connection can access and potentially update. If the application needs to handle data for multiple companies, it needs to handle multiple API connections.

Setup


API connections are currently created and maintained by the Avinode and Schedaero support staff.

Application Specific


If different kinds of applications are implemented, each application should be able to use separate API connections.

Automatic Expiration


API connections that are not used for 60 days are automatically deactivated.

HTTP Request Headers


Several HTTP headers are required in every request to authenticate and provide other details about the call.

HTTP Request Headers

X-Avinode-ApiToken


This required field is a unique token identifying the calling application. The value for the API token should not be editable by the users of the application. It is preferably hard coded into the application.

X-Avinode-ApiToken example
X-Avinode-ApiToken: 229B8C9E-B3F2-4FA6-8BAE-71DF00943C0E

🚧

Important:

The API token is used to identify the calling application. To prevent malicious callers from impersonating other software, the API token must not be shared with any external parties that are not directly involved in the project. Posting code examples, curl commands or similar to online forums or discussion groups where the API token is included is strictly forbidden.

Authorization


This required field must contain the unique token that identifies the API connection that should be used for this call. When sending this, the HTTP header with the token must be prefixed by the word ‘Bearer’ in the style of OAUTH tokens.

📘

Please Note:

When using the Sandbox Swagger page, the ‘Bearer’ prefix will need to be added.

Authorization example
Authorization: Bearer mF_9.B5f-4.1JqMklj3498dfoFWrw-89qnavn.8234Klnj843jw09ksU

📘

Important

Since the authorization token is used to identify and authorize the caller, it must be treated with the same care as any username and password. It must not be shared with any external parties that are not directly involved in the project. Posting code examples, curl commands, or similar to online forums or discussion groups where the authorization token is included is strictly forbidden.

X-Avinode-SentTimestamp


This field is required and must contain a timestamp formatted in accordance to ISO-8601. This is the time of creation for the message. The call will be rejected if this time is off by more than 5 minutes when the message is received. So it is important that the clock used by the application is up to date at all times.

X-Avinode-SentTimestamp example
X-Avinode-SentTimestamp: 2016-01-19T08:10:06.135Z
X-Avinode-ApiVersion


This field is required and must contain the API version that the application will use.

X-Avinode-ApiVersion example
X-Avinode-ApiVersion: v1
X-Avinode-ActAsAccount


This is an optional field. Some operations support sending a personal Avinode Marketplace account username. This means that this person will be registered as the user doing the action of the operation. For example when uploading an RFQ, the system will show the provided user as the user requesting the quote. The documentation page for each operation handling this HTTP header will have more information about this.

X-Avinode-ActAsAccount example
X-Avinode-ActAsAccount: johnsmith64
X-Avinode-Product


This should always be populated with the name and version of the calling application.

X-Avinode-Product example
X-Avinode-Product: Smart Flight Finder v2.3

HTTP Status Codes

The APIs use conventional HTTP response codes to indicate success or failure of each API call. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, an authorization failed, etc.), and codes in the 5xx range indicate an API server error.

Response Code

Response Text

200

OK

201

Created
The server created one or more entities as a result of the call

400

Bad Request
The request was somehow invalid. e.g. bad timestamp, etc ...

401

Authorization Failure
Bad token, no permissions, rate limit exceeded, etc ...

404

Not Found
The application requested a resource that does not exist

422

Entity Invalid
Validation failure, relationship failure, or state failure

500

Internal Failure

501

Not Implemented
The called operation is disabled, or not yet implemented

503

Service Too Busy

504

Service Temporarily Unavailable

HTTP Response Headers

🚧

Service Rate Limits

Please note that Service Rate limits (below) are implemented for our Avinode Marketplace APIs, this is not a current response you will see from accessing Schedaero APIs.

Service Rate limits


The number of calls that one API connection can make per hour is limited. Every API response will include the following HTTP headers. After the number of calls has reached the rate limit, all calls to that service will be denied with the HTTP 403 response code until the next hour starts.

X-Rate-Limit-Limit


The rate limit for the service that was invoked. This is the allowed number of calls per hour.

X-Rate-Limit-Remaining


The remaining number of calls allowed within the current hour.

X-Rate-Limit-Reset


The number of seconds until the call counter is reset (i.e. the next hour starts).

Implementation

Internationalization


Dates and times are formatted in accordance to ISO-8601.

Currency


Currency codes use the three letter code defined in ISO 4217. Price conversions are based on Forex data which is updated daily from Xignite.

Country Codes


Country codes use the two letter code defined in ISO 3166-1 alpha-2.

Province Codes


Province codes use the format defined in ISO 3166-2. Each code consists of two parts, separated by a hyphen. The first part is the two letter country code and the second part can be up to three letters specifying the region in that country. For example; “US-FL” for Florida.

Sparse Fields


For some operations, there is information available that will only be included in the operation output if it is requested when making the API call. This extra information is requested by specifying one or more values in the operation’s field[operation] URL parameter. The documentation page for each operation has information about the available sparse fields.

IDs


Unless specifically stated in this documentation, the format of any object’s identifier is unspecified, and can change at any time. For example, an operation that currently returns an ID that looks like “abc-12345678” could change to “1234-ABCD-5678-EF90”. The calling application should not try to extract parts of the these IDs for any reason. If the format of an ID changes, the API operations using this ID as input will continue to support previous formats. The application should not display any API generated IDs to the user unless this documentation specifically states that the particular ID can be String Handling.


Data entered in string properties must conform to the following rules:


  • If a string contains multiple lines then new lines must either be sent as line feed (\n) or carriage return and line feed (\r\n).

  • If a string contains a backslash character (\) then it must be escaped with an additional backslash character (\\).

  • If a string contains a double quotation mark (") then this must be escaped with a backslash character (\").


Data returned in string properties should be displayed correctly to the users of the application according to the rules above.

Retry Policies


If a call to the API fails for any reason, a retry policy should be sensibly implemented. This would most likely include concepts like exponential back-off, maximum number of retries, etc… For some operations, retries are not allowed. The documentation page for each operation may have information about the recommended retry policy

Automatic Testing


No automatic tests are allowed to make calls to the API. This applies to all types of automatic testing such as load tests, integration test suites, etc… All logic generating calls to the API must be replaced by mock-ups when running automatic tests. This is true for both our Production environment as well as the sandbox environment

API Contracts


The contracts in place for each member or partner using the APIs regulates how the APIs can be used, and how the data returned by the APIs can be handeld. Paragraphs regulating the following can be included:


  • Which API related use cases the application can implement

  • How, and for how long, certain data returned by the APIs can be stored

  • How, and to whom, data returned by the APIs can be shared

Abuse


Calling any API operations in any repetitive or automated fashion for the purpose of harvesting information is strictly forbidden.

👍

Implementation Checklist

  • The application only implements API call related use cases that are approved by Avinode or Schedaero
  • The application does not store any data, returned by the APIs, that is not allowed to store
  • The application does not share any data, returned by the APIs, that is not allowed to share
  • The application’s API token (the token sent in the X-Avinode-ApiToken HTTP header) is hard coded into the application and not configurable by the users of the application
  • The application always sends its name and version in the X-Avinode-Product HTTP header
  • The application does not display API generated ID's to the user, unless this documentation specifically states that the particular ID can be displayed
  • The application does not, for any reason, extract any parts of an API generated ID
  • The application handles Authentication Tokens with the appropriate level of security to avoid it from falling into the wrong hands
  • The application escapes and handles string data according to the specified rules
  • The application can handle that an operation suddenly returns properties that wasn’t returned at the time of implementation
  • The application has sensible retry policies for failed calls to operations that allow retries
  • Instances of the application built or deployed for development or testing purposes cannot call the live API servers or consume live web-hook notifications

Did this page help you?