Using our APIs

URLs

The APIs are designed to have predictable, resource-oriented URLs that make writing applications easy. We have embraced the core principles of REST and use standard HTTP response codes to indicate the success or failure of API requests.

HTTPS Methods

Our APIs use appropriate HTTP verbs for every action.

• GET - used for retrieving resources.
• POST - used for creating resources and performing resource actions.
• PUT - used for updating resources.
• DELETE - used for deleting resources.

Inputs and Outputs

In the majority of cases, both request body data and response data are generally formatted as JSON. Refer to the API documentation in the API Catalogue to see where other formats or media types are supported.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Developer area, be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth. API requests without authentication will fail.

Secure HTTP support

To ensure data privacy, only calls made over HTTPS are supported. So all requests to an API endpoint will have to be SSL/TLS compliant, furthermore only TLSv1.2 or higher protocols are supported. Calls made over plain HTTP will fail.

Status Codes

Our APIs communicate errors through standard HTTP status codes with details supplied in JSON objects. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (eg, a required parameter was omitted), and codes in the 5xx range indicate an error at our end of the process.

Long Running Operations

Several of our APIs perform compute intensive mathematical operations that can take an extended period of time. These APIs use the Long Running Operations (LRO) pattern as documented in Microsoft REST API Guidelines. 

APIs that implement the LRO pattern obey the following protocol when a client application initiates an API call:

1. The API validates the request, and either sends an error response if validation fails, or sends an operation response, including a link to the location at which the caller can obtain results of the transaction.
2. The client application queries the link returned in the operation response. If the transaction has completed, the query returns the results of the operation, else, the query returns a "not ready yet" response, together with status information.
3. The client periodically re-queries the operation response link until the query returns the results of the operation

View Long running operations flow diagram

Long Running Operations API details

Pagination

Where applicable, API resources have support for bulk fetches via "list" API methods. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Versioning

We strive to make API changes backwards-compatible. When we make breaking changes, we increment the version.

Accept: application/vnd.github.user+json;version=2017-04-20

All requests must explicitly specify the API version otherwise an 406 Not Acceptable response will be returned.

When you first adopt an API, using the latest version is recommended where possible. The API Catalogue contains information and documentation for all version releases.