Published in


Setting Oracle Integration Standards

This is an introduction to one element of API3's technical design.

Piet Mondrian, Composition with Red, Yellow, and Blue. 1942, Tate Modern, London. (Detail.)

The API3 solution to the API connectivity problem requires an ecosystem with a large number of first-party oracles. Airnode’s role in this is to make first-party oracles a reality.


Airnode is an oracle node specifically engineered for API-provider operated oracles (i.e. first-party oracles). It is designed to interface APIs to smart contract platforms. This results in some very restrictive requirements. Such requirements are outlined in Section 4.2 of the API3 whitepaper.

Here, we will only focus on one of these requirements: standardized integration.

Standardizing API⬌Oracle Integration

API–oracle node integration should be standardized so that general and comprehensive tools can be developed to streamline the process.

To integrate a System X to a System Y, we need to do three things:

  1. Specify the interface of System X.
  2. Specify the interface of System Y.
  3. Specify how the interface of System X maps to the interface of System Y.

OpenAPI Specification (OAS)

Luckily, one system that we are interfacing — namely, a Web API — already has a robust and well-adopted interface standard: the OpenAPI Specification (OAS).

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs […] When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

Our own Oracle Integration Specification (described below) is largely inspired by OAS and designed to elegantly interface with existing Web API standards.

Oracle Integration Specification (OIS)

The Oracle Integration Specification (OIS) is designed following the exact steps described above:

  1. API operations are specified.
  2. Oracle endpoints are specified.
  3. Oracle endpoints are mapped to API operations.

Therefore, the only thing an API provider needs to do — in order to integrate an API to Airnode — is to create an OIS. This can be done by reading the OIS docs and creating the OIS for the specific API and use-case.

Even simpler, we’re building tooling that converts an API provider’s existing OAS file to a valid OIS file.

For the following diagram, I borrow rather loosely from Entity Relationship (ER) Diagram notation, in order to visually show how OIS integrates with OAS, but I think this looseness is sufficient for our relatively informal purposes here.

A visualization of how Oracle endpoints are mapped to existing API operations via the Oracle Integration Specification (OIS)


OIS is a JSON file, designed to describe the integration specifications for Airnode to use. This means that it does not aim to be human-readable first and creating it manually to specify an integration might potentially be difficult for some users.

This problem will be solved by ChainAPI, an integration platform that will allow users to generate OIS for their APIs through an easy-to-use graphical interface. As a result, API3 will have a wide selection of first-party oracles to compose dAPIs from and ecosystem growth will no longer be bottlenecked by integration capacity.

Further Documentation

For more thorough and formal documentation, see:



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store