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.
Each API connection has a set of permissions that restrict which operations can be called.
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.
API connections are currently created and maintained by the Avinode and Schedaero support staff.
If different kinds of applications are implemented, each application should be able to use separate API connections.
HTTP Request Headers
API connections that are not used for 60 days are automatically deactivated.
Several HTTP headers are required in every request to authenticate and provide other details about the call.
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
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.
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.
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
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.
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
This field is required and must contain the API version that the application will use.
X-Avinode-ApiVersion example X-Avinode-ApiVersion: v1
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
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
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.
Service Too Busy
Service Temporarily Unavailable
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.
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.
The rate limit for the service that was invoked. This is the allowed number of calls per hour.
The remaining number of calls allowed within the current hour.
The number of seconds until the call counter is reset (i.e. the next hour starts).
Dates and times are formatted in accordance to ISO-8601.
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 use the two letter code defined in ISO 3166-1 alpha-2.
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.
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.
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.
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
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
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
Calling any API operations in any repetitive or automated fashion for the purpose of harvesting information is strictly forbidden.
- 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
Updated over 2 years ago