Skyward APIs

Don’t have the resources or expertise to build out an API dashboard for your drone program from scratch?

Skyward offers pre-built reporting dashboards in PowerBI for insights into your drone program. Please contact Customer Success at [e-mail] for more information and assistance.

Introduction

Welcome to the externally accessible API for Skyward Enterprise customers. This document is designed to help you become familiar with the basic concepts of the Skyward API and includes code, call, and responses examples to get you started.

The Skyward API is a REST API, specifically JSON over HTTP.

Availability

Skyward's externally accessible API is available for customers with Enterprise subscriptions. Please contact Skyward's Customer Success Team at [e-mail] for more information on subscribing or upgrading your account.

Documentation

The main sources of documentation for Skyward APIs are:

• The explanation of basic concepts in this document
• Code, call, and responses examples included below
• The online OpenAPI reference documentation of all endpoints, which will be made available to Skyward Enterprise subscribers. This documentation is made using the OpenAPI specification (also known as Swagger). It allows you to interactively try out endpoints.

Warning

• Be advised that the online OpenAPI reference documentation lets you try out endpoints against our real, live production environment. If you do not wish to make changes to the production data of your organization, please contact Customer Success for assistance in advance.

Requests

The Skyward APIs consume and produce JSON payloads over an HTTPS connection. However, some requests may also require no payload and produce no payload.

• A valid base URL is required for all endpoints (in this document referred to as ${BASEURL}).
• An endpoint is identified by its request path ("/api/some/path").
• Often one or more request parameters are included in the request path ("/api/some/path/${someId}").
• Additional properties may further change the request, such as query parameters ("?owningOrgUuid=...&status=...") and HTTP headers ("Authorization: ...").
• Many of the concepts in our system are uniquely identified within our system by UUIDS in their canonical textual representation (e.g. 0d05f42c-6e3f-4e88-8195-72e09800584d).

Verbs

In general, the Skyward API is modeled around core business concepts in our system, such as:

• Aircraft
• Batteries
• Checklists
• Flights
• Operations
• Persons

For each of these concepts, Skyward APIs may offer a number of endpoints using different HTTP verbs, such as:

• DELETE: mark items as deleted, typically one per request
• GET: get items; you would typically see different endpoints for getting a single item, or for multiple items
• PATCH: partially update an item, based on instructions in the payload
• POST: create a new item, to the image of the payload
• PUT: fully update an item, to the image of the payload

Responses

Unless explicitly documented otherwise, payloads will be JSON, specifically JSON objects (preferred) or JSON arrays. This means that a payload will not be a primitive value like a string, number, boolean.

Response payloads are designed to be simple and discrete. Whether the response payload is a single item or multiple items, they are all of a single type, describing a simple core business concept.

While responses may include references (UUIDs) to items of other types, details for other items are not included in the main response payload. This makes for simple endpoints that return small payloads.

List Responses

If the response payload of a request can contain multiple items, these items can be found as an array under the content key. Additional keys are included with information about the list of responses. The following keys are supported:

• content: array of multiple items
• first: whether the current page is the first one
• included: see the paragraph "Additional Includes"
• last: whether the current page is the last one
• number: the number of the current page
• numberOfElements: the number of elements currently on this page
• size: the size of the page
• sort: the sorting parameters for the page
• totalElements: the total amount of elements
• totalPages: the number of total pages

Pagination

If the response payload of a request can contain multiple items, these items will always be paginated. Only a single page is returned per request. A specific, 0-based page number can be requested using the page query parameter. A desired page size can be requested using the pageSize query parameter, and must be at least 1, and at most 100. If you want more than 100 items (i.e. if you want all items), it will be necessary to request multiple, consecutive pages. The default page is 0 (the first page). The default page size is 50.

Additional Includes

Sometimes an additional item of another type in addition to the main response payload is desired. For example, you want to know the name of an organization UUID that is referenced in a response payload, or the operation to which the flight in a response payload belongs. For this, additional items can be included. Additional items can be included by requesting them using respective @@include query parameters, as described in Skyward's OpenAPI reference documentation of endpoints. The original, main response payload can be found under the content key, while the additional items can be found under the included key. For example, if personUuids are found in the main response payload, more details of these persons can be requested using the @@include=person query parameter, and the respective persons are included under the included.person key, like so:

Status Codes

The result of a request is indicated with an HTTP status code. Some interpretations of common status codes:

Successful:

• HTTP 2xx: the request was successfully completed

Unsuccessful:

• HTTP 400 Bad Request: some request parameter was invalid
• HTTP 401 Unauthorized: you could not be authenticated, because your access token is invalid or missing
• HTTP 403 Forbidden: you could not be successfully authorized to perform the request, for example because you are not a member of the organization, you don't have the appropriate roles, or you need to refresh your access token for the organization in the request
• HTTP 404 Not Found: the requested item could not be found; this status code is only used when the item that is the main subject of the request could not be found; if some related, required item could not be found rather a HTTP 400 Bad Request is the result
• HTTP 409 Conflict: due to an illegal state the request could not be successfully performed; a typical example is that an item could not be created because it already exists
• HTTP 429 Too Many Requests
• HTTP 5xx: something is wrong at the Skyward API; operations staff at Skyward will be notified whenever this happens, or you may contact the Customer Success team of Skyward for more information

For unsuccessful results, the response payload is mostly standardized, and has the following properties:

• error: reason phrase of the HTTP status
• exception: type name of the programmatic exception that was involved
• message: brief hint or explanation why the request was unsuccessful
• path: request path
• status: code of the HTTP status (number)
• timestamp: date/time of the response

Data Types

Dates

Dates are formatted either as:

• ISO 8601 combined date and time representation, e.g. "2019-02-19T00:28:21.646Z". Note that here the milliseconds are not optional
• Milliseconds since Unix epoch

Item Identifiers

Items are generally identified by strings that contain unique identifiers, looking something like "1e9bb85b-5240-4c7b-a74b-e34c4fb5f165".

Authentication

Two types of authentication principals are supported:

• Person: a human user; or an
• Enterprise: an organization, typically some centralized process of the organization that it represents

Authentication follows a two-step approach:

1. Exchange credentials for an access token
2. Use the access token on requests to the other endpoints of the Skyward API

Credentials can never be used directly on other endpoints of the Skyward API.

Exchange Credentials

Person

Credentials of a human user are the same as they use for login to the Skyward user interface. A human user can submit their user name and password in exchange for an access token and a refresh token.

Online OpenAPI reference documentation about the credentials exchange for a human user can be found at ${BASEURL}/swagger-ui.html?urls.primaryName=Auth%20Tokens%20API#/auth-api-controller.

Example:

Here BASEURL is the provided URL to the Skyward API, and USERNAME and PASSWORD are the same credentials as for login to the Skyward user interface.

Access tokens are associated with specific organizations. When making requests related to a specific organization, that organization must be included in the access token. (Although, for some requests it suffices to include an organization in the access token that is a parent in the enterprise organization hierarchy of the specific organization that the request relates to.)Specific organizations can be explicitly included while exchanging the credentials by including the organizationUuid query parameter. The user must have existing access to the requested organizations. To log into a different organization, the access token also needs to be refreshed, while specifying the requested, different organizations to log into.Most commonly, the access token includes a single access token, but an access token can be requested to include multiple organizations by repeatedly including the organizationUuid query parameter.If no organization is explicitly requested, the last used organization is included in the access token. This can be confusing and it is recommended that client code be explicit about organizations to include in the access token.

Enterprise

Credentials of an enterprise principal must be supplied explicitly by the Skyward Customer Success team. These credentials are not the same as those one used to login to the Skyward user interface. An enterprise principal can submit its login name/user name and password in exchange for an access token.

Online OpenAPI reference documentation about the credentials exchange for an enterprise principal can be found at ${BASEURL}/swagger-ui.html?urls.primaryName=Auth%20Tokens%20Enterprise%20API#/authentication-controller.

Example:

Here BASEURL is the provided URL to the Skyward API, and LOGINNAME and PASSWORD are the credentials as explicitly supplied for your organization, by the Customer Success team of Skyward, for usage with the Skyward API.

Response

The response from the credentials exchange looks as follows:

The accessToken is used for requests to other API endpoints. The refreshToken is used for obtaining a new access token.

Using an Access Token

Access tokens can be used on other API endpoints by including an HTTP header as follows:

For example:

Refresh Access Token

The access token gives access to other API endpoints, and has a relatively short expiration time. The refresh token has a relatively long expiration time. The expiration times are included when any new tokens are returned. The human user can submit the refresh token in exchange for a new access token and a new refresh token. They should do so just before a token is about to expire, or when the access token is already expired. If the refresh token is expired, they should start over and submit their user name and password for new tokens.

Example of refreshing the access token for a human user:

Here BASEURL is the provided URL to the Skyward API, and REFRESHTOKEN is the refresh token that you obtained from an earlier credentials exchange or refresh.

For a human user, the specific organization(s) can be explicitly included for a refresh by including the organizationUuid query parameter. This does not need to be the same organization as on any earlier credentials exchange or refresh. The user must have existing access to the requested organization. For more about access to organizations, see the paragraph about credentials exchange (above).

The response from the refresh looks the same as the response from the credentials exchange.

Authentication Lifecycle

Summary of several common authentication scenarios:

Retrieve an access token:

1. Offer credentials to authentication endpoint (optionally specify the requested organization)
2. An access token and a refresh token are returned

Get access to a specific endpoint of the Skyward API:

1. Offer access token as authorization header on the request: Authorization: Bearer TOKEN
2. The endpoint performs the request

Refresh an (expired) access token:

1. Offer refresh token to authentication endpoint (optionally specify the requested organization)
2. A new access token and a new refresh token are returned

Refresh an (expired) refresh token:

1. Go back to "Retrieve an access token"

Get access to a service of a different organization:

1. Go back to "Refresh an access token", specify the requested organization

Versioning

Skyward is continuously improving our APIs. Non-breaking changes are released into the existing APIs at an ongoing basis. This means that any client code should remain compatible with these updates to the Skyward APIs. If there is any breaking changes to an API endpoint, a new major version is introduced. Major versions of API endpoints are identified by the first segment in the request path: /api2 (V1), /api2 (V2), /api3 (V3), et cetera. Versioning is per endpoint, there is not an overall version of the Skyward API.

Throttling

In accordance with your user agreement, your application must be a well-behaved user of  Skyward APIs. In the case of excessive usage, requests may be throttled. Throttling may happen on specific endpoints, or for all requests of the same authorized principal. Throttling manifests by the Skyward API responding with a 429 status code ("Too Many Requests").

Client code should be resilient against throttling. You are recommended to implement a strategy of retries combined with progressive back-offs (for example exponential).

Specific attention is asked for authentication. You should reuse access tokens and refresh these using a refresh token. Please do not authenticate with your credentials, to request an access token for single use, for/before every request.

Support

Please contact  Customer Success at [e-mail] for more information and assistance in your use of  Skyward APIs.