The API3 Technology Stack

A brief introduction to the hierarchy of layers that make up the API3 first-party oracle technology stack.

As Burak stated in dAPIs: APIs for dApps, “the goal of API3 is to build, manage and monetize dAPIs at scale” … “which means creating a dAPI economy that is comparable to Web3 as a whole”. In order to achieve this ambitious goal, API3 technology is designed as a hierarchy of layers “to allow the user to pick the most suitable tool for the job.”

dAPIs (managed API services for dApps)

At the top of the stack are dAPIs. These are the highest level tools in the API3 toolkit. dAPIs are managed API services designed to resemble Web APIs from the perspective of a smart contract. dAPIs have the following characteristics:

• The dApp pays for a service which the API3 DAO provides transparently and transactionally. There is no commitment from the dApp or entanglement with the API provider.
• They have a standardized, user-friendly interface that intends to abstract away the technical implementation.
• They exist entirely on-chain as smart contracts and use off-chain first-party oracle primitives such as Beacons under the hood.
• They are expertly managed by the API3 DAO so the dApp does not have to worry about API provider availability or longevity. dAPIs dynamically adapt to changes in API availability.
• The dApp is covered by the API3 DAO against losses due to malfunctions. This risk protection from the API3 DAO makes dAPIs quantifiably secure.

dAPIs are the easiest to use and most automated tools in the API3 tech stack. Being more resilient to API provider uncertainty, dAPIs come with more coverage, and therefore a greater amount of quantified security.

dApps should use dAPIs by default and only delve into lower layers when they have a good reason.

Beacons (first-party oracle primitives)

In the middle of the stack are Beacons. A Beacon is a first-party data feed hosted and operated by the API provider itself, and powered by Airnode. Beacons are primarily used as building blocks to make dAPIs but they can be used directly by dApps when necessary. Beacons have the following characteristics when used directly:

• The dApp is entangled with the API provider’s data feed. If the API provider stops providing the feed or the dApp wants to switch to a new API provider then the dApp has to make the change.
• The dApp is still risk protected by the API3 DAO from losses due to malfunctions but Beacons come with less coverage than dAPIs. Beacons are less resilient to API provider uncertainty because the dApp depends directly on the API provider.
• Beacons can be accessed individually or combined into “Beacon sets” which aggregate data from multiple sources. A Beacon set is static — its data sources are fixed permanently. Beacons cannot be added to or removed from a Beacon set like they can with a dAPI.

Beacons are usually used as building blocks for dAPIs. Examples of situations where a dApp might prefer to use Beacons directly instead of dAPIs are:

• The dApp needs a data feed from a specific API provider on a specific chain but there isn’t a dAPI for that feed from that provider on that chain.
• The dApp and/or API provider are much larger than the API3 DAO and the coverage that can be provided by API3’s risk protection is insufficient, so it makes more sense for the dApp and API provider to connect directly with each other.
• The dApp is required to work directly with the API provider due to contractual or regulatory reasons and an API3-managed dAPI would create a conflict.

Beacons are lower-layer first-party oracle primitives that can be used as needed, making the API3 tech stack more scalable, both up and down.

dApps can use Beacons directly but should prefer dAPIs by default and only use Beacons when necessary.

Airnode Protocols

At the bottom of the stack are Airnode protocols. These are the underlying rules and communication standards that make Beacons and dAPIs possible. Directly using Airnode protocols provides dApps with the most control over their interactions with APIs but it also requires more effort and expertise.

Examples of Airnode protocols are:

Request-Response Protocol (RRP)

RRP models the traditional Web API paradigm in which a client makes a request to a server and then waits for a response to come back. With RRP the “client” is your smart contract. Airnode provides the plumbing for a smart contract to send requests to a Web API and receive back responses.

An example of when to use RRP directly is when your smart contract needs to pass parameters with the request that aren’t fixed — they change with each request.

For example, imagine that your smart contract needs to know about the weather in the city where the user is located, and every user is in a different city. It wouldn’t be efficient to run a continuously-updated data feed that provides the weather for every city in the world. Instead, dApps can use RRP directly and pass the city as a parameter when the smart contract sends its request. We call this usage pattern Web3 APIs.

Publish-Subscribe Protocol (PSP)

PSP, also called “pub-sub protocol”, is another Airnode protocol that can be used to build Beacons. The difference is that with PSP the API provider initiates communication. Instead of waiting for requests from the smart contract, the API provider “knows” when to send responses and just sends them at the right time.

When a smart contract uses RRP it’s like doing a Google Search. The contract sends a request with some parameters (the search terms) and gets back a response with the matching web pages almost immediately.

When a smart contract uses PSP it’s like subscribing to Google Alerts. The contract subscribes to be notified any time in the future when web pages are found that meet the criteria set by some parameters (the search terms).

The advantage of PSP over RRP is that PSP can be more efficient. In the “RRP weather” example above, if the smart contract wants to send money to a customer when the temperature in Orlando, Florida reaches 100°F, the customer would have to manually check the temperature and request the money. It would be better if this happened automatically. But in order to make the process automatic with RRP, the smart contract would have to request the temperature every day, which would be expensive due to gas.

Alternatively, the smart contract can use PSP and subscribe to be notified whenever the temperature in Orlando reaches 100°F, which is automatic and far more efficient. PSP lets a smart contract offload the work of repeatedly checking the temperature to the off-chain API provider which is faster and avoids paying for a lot of gas.

dApps can use Airnode protocols directly but should prefer dAPIs or Beacons for typical data feeds with fixed API parameters.

The Big Picture

The API3 technology stack is a hierarchy of layers that build on each other. dApp developers can work with the highest layer, dAPIs, for the easiest, most resilient, and least risky access to off-chain APIs. Or they can choose to work with the lower layers, Beacons and Airnode protocols, if they have extenuating needs that aren’t met by dAPIs.

Smart contract developers should:

• Use dAPIs by default. They’re the easiest and most quantifiably secure.
• Use Beacons directly if they want data feeds but the dAPIs provided by API3 don’t meet their needs.
• Use Airnode protocols directly if they want low-level access to API parameters and responses.

The API3 technology stack is designed as a hierarchy of layers to easily serve the most common cases while flexibly scaling up and down to serve the less common cases.

Author: Ryan Boder