Integrating with Apiary

Apiary offers a way for 3rd party applications and partners to integrate with its services and tools.

Overview

When your organisation have specific needs or your application can benefit from connecting with Apiary, you can use Apiary’s Integration API - enterprise-integrations.apiary.io.

» Integration API documentation on Apiary

Team APIs only

This functionality is available only for team API Projects.

Capabilities

Through Integration API, you can request details about team projects saved in Apiary. Integration API also adds few other features on top.

API Description Document management platform

GitHub Integration, API Blueprint and Swagger style guide validations and API testing makes Apiary perfect as a source of truth for API Description Documents. Integration API allows you to sync current state of API Projects with your application.

Embed your API documentation

When you request details about API Project, you will also get back details on how to embed API Project on your domain. Integration API response contains short-lived and scoped token for embedding specific project so it’s suitable even for public facing websites and portals.

On-demand Mock Server

Mock Server design is based upon Mock Server used in Apiary.io application and is documented in Apiary Help: Mock Server with few additions and changes in behavior.

Mock Server URL can be obtained by requesting detail of an API Project. Mock Server URLs will have different hash as an identifier. Mock server URL is available without any other additional steps. Endpoints described in API Description Document are available for requests.

Mock Server URL served through Integration API is amnesiac. Server is not recording request nor response payload or headers.

Technical details

How to get access

Registration of OAuth apps is not currently opened to public.

OAuth 2

Our OAuth server supports 3-legged OAuth 2 with support for Refresh Tokens. You can learn more about required OAuth flow and endpoints in Apiary Authorization API.

In general, your OAuth flow should look like so:

acquire user’s authorization_code by redirecting user to an OAuth authorize page
exchange this authorization_code for user-scoped access_token and refresh_token
use access_token to access user’s resources
use refresh_token to get fresh access_token when current one expires (expiration date is readable, as all tokens are JWT)