api3dao / api3-docs

Documentation for the API3 Project

Legacy Documentation

⚠️ Please note: These docs are now legacy. The only changes to them should be corrections, no enhancements. Go to the vitepress-docs repo for the current documentation. ⚠️

API3 Documentation is kept as a regular repository of Markdown files making it easy for everyone to contribute. Feel free to create issues for discussions, proposed additions and changes.

What is API3?

API3 is a collaborative project to deliver traditional API services to smart contract platforms in a decentralized and trust-minimized way. It is governed by a decentralized autonomous organization (DAO), its code is open source and its operations are transparent.

API3 Thesis Statement

The vast majority of the external integrations that decentralized applications need are to commercial Web APIs that traditional businesses have built to monetize their data and services. Therefore, what is widely known as the oracle problem is in practice the API connectivity problem. Existing oracle solutions fall short because they fail to make this distinction, resulting in inferior solutions that depend on third-party oracles and ecosystems that exclude API providers. By refining the definition of the problem, API3 aims to provide a much more optimal solution.

Whitepaper

See the whitepaper for a detailed discussion of the project. Just as these docs, you can discuss it and propose updates through issues.

Medium Posts

See a grouped list of our Medium posts here.

Become a part of API3

API3 is formed by people who spontaneously found each other through a common understanding. Despite being largely overlooked, the API connectivity problem is the most critical obstacle in front of meaningful decentralized applications being built at scale.

If existing oracle solutions do not fulfill the needs of the decentralized applications you want to build, give you a fair opportunity to monetize your API business, or feel like they are working against the ethos of decentralization, we invite you to be a part of API3 so that we can solve the API connectivity problem together. If you are coming from a technical background, see our Documentation and get started contributing.

The API connectivity problem is in essence an ecosystem building problem, more so than a technical one. This means that API3 can use the skills of all kinds of experts and the decentralized nature of the project will allow you to shape it in a way that makes the best use of your skills.

Communication Channels

Website: https://api3.org/

Forum (for community): https://forum.api3.org/

Telegram (for community): https://t.me/API3DAO

Discord (for contributors): https://discord.gg/qnRrcfnm5W

Medium publication of the DAO: https://medium.com/api3

API3 Documentation

api3-docs's Issues

Protocol solidity class chart

There is a protocol solidity class chart that Ashar build. If this lives in the Airnnode repo it may be worth linking to it.

protocol solidity class chart

Sidebar doesn't autoscroll to the selected item

When the user follows a link (for example click https://api3dao.github.io/api3-docs/next/grp-providers/protocols/request-response/designated-wallet.html from an external page) the sidebar should automatically scroll to make the current page visible.

Document Airnode request error codes

Requests coming to Airnode can be set to status = "Errored" for a number of different reasons. Each of these reasons has a specific "error code" integer that is returned to the calling contract as the statusCode argument here: https://github.com/api3dao/airnode/blob/6f31a4c27d40e86101673bf37d223fef6625dfdd/packages/protocol/contracts/AirnodeRrp.sol#L148 A status of 0 indicates success, while a status of > 0 indicates that an error occurred and the integer can then be used to determine what exactly went wrong.

Currently, this list of error codes is documented here: https://github.com/api3dao/airnode/tree/master/packages/node#behaviour but this should rather be documented in the Airnode RRP documentation. The list of error codes and their descriptions should not be in a Google sheet.

Testing Integration with Github Documentation project

Create walkthrough videos for running the node locally

Reserved parameters example for /next out of sync with /pre-alpha

The reserved parameters example for /next seems to be out of sync with changes added to /pre-alpha on 2021-06-23.

See http://localhost:8080/next/technology/templates/config-json.html

My guess is /next has additional elements that pre-alpha does not but wondering if the last element (carried over from pre-alpha) should have a second key.

Below is /next

"reservedParameters": [
              {
                "name": "{FILL_*}",
                "fixed": "{FILL_*}"
              },
              {
                "name": "{FILL_*}",
                "fixed": "{FILL_*}"
              },
              {
                "name": "{FILL_*}",
                "default": "{FILL_*}"
              },
              {
                "name": "{FILL_*}"
              }
            ],

Below is pre-alpha

"reservedParameters": [
            {
              "name": "{FILL_*}"
            },
            {
              "name": "{FILL_*}"
            },
            {
              "name": "{FILL_*}"
            },
            {
              "name": "{FILL_*}"
            }
          ],

Also this may be the case here for the osi.md template:

https://github.com/api3dao/api3-docs/blob/pre-alpha-relay-metadata-docs/docs/pre-alpha/guides/templates/ois-json.md

Add logFormat/logLevels to config.nodeSettings

config.json specs in the next version is missing logFormat and logLevel, they need to be added

Remove the id field from config.json

See api3dao/airnode#411

After we remove the id field from config.json, we need to also remove it from the /next docs

Blog posts navbar item

Copy-pasting from YEET on Discord:

https://docs.api3.org/pre-alpha/#learn-more-about-api3 I'd suggest this to have it's own page and not buried in "What is API3" page. More specifically "Blog Posts" tab should be easy to reach.
All the other sections like API3 website, The whitepaper, communities, github are mentioned either in top navigation bar or other pages. Except "Blog Posts" section.

I agree, it's a good idea to have blog posts as a navigation bar item. Also, they should be very up-to-date.

VuePress TOC not playing nicely with browser history

Links in documents have the proper behavior when linking to another document. Using the back button returns to the sending document at the same position the user left.

However, if you use the TOC on a doc to scroll down to a particular position and then use a doc link to go to another and then return, the position in the sending doc is lost and the user is sent to the top of the sending doc.

Add Validator doc

There is nothing on the docs site about the Validator.

Refer to airnode-admin wherever applicable

When the docs or guides mention an action that airnode-admin can do (e.g., a requester endorsing a client), refer the reader to the related airnode-admin functionality.

API key should be filled

If I understood correctly API key in config.json has to be filled out or provided in .env file. This makes description here deprecated, as the related issue was closed.

Remove /next from version pick-list

It may make sense to remove the /next version from the version's pick-list.

Currently, /next is not included in the pick-list on production. It is however within the pick-list for local development. This does not mirror production while in development.

Below is how the pick-list looks in development.

New version rules:

• All subfolders in /docs are base routes
• A base route becomes a version of the docs when declared a version in config.json

  versions:[
    {"name":"0.1.0", "url":"/0.1.0/"},
    {"name":"pre-alpha","url":"/pre-alpha"}
  ],

Under these new rules /next is still accessible in production and development by using the browser's URL bar.

markdown-link-check not catching anchor links

markdown-link-check does not appear to be catching bad links with anchors (#secrets-env) attached. Seems to return true because it only checks the URL up to the anchor. May be able to use $page.headers to check anchors. Not sure how that might work but first will look for another plugin that might already do so.

Roles aren't collapsible

Roles should be automatically expanded but also collapsible. The sidebar grows too large at the moment.

DAP docs (pre-alpha) - Linux/Firefox has blank pages

Some images are named myImg.PNG but referenced in code as myImg.png. Linux is case-sensitive when referencing files. Maybe change all file extensions to .png rather than .PNG

Enclose %cd% by quotations in Docker commands for Windows

Windows users replace $(pwd) with %cd% while using the Docker commands. However, if the path returned by %cd% contains any whitespace, Docker throws Invalid Reference Format. We should use "%cd%" instead.

See this issue for more information:
api3dao/airnode#457

Check for broken hyperlinks

We should use a tool for validating that all hyperlinks are still valid.

A quick google search found this: https://github.com/tcort/markdown-link-check which actually also has Github actions integration: https://github.com/gaurav-nelson/github-action-markdown-link-check

There may be other, more suited tools out there - this was just the first one I found.

Move Docker image documentations to api3dao/api3-docs

Move Docker image documentation
https://github.com/api3dao/airnode/blob/daf3108517386ba424335c3fcfeb57b2338a658f/Docker.md
https://github.com/api3dao/airnode/blob/daf3108517386ba424335c3fcfeb57b2338a658f/Docker-client.md
(from all branches) to https://github.com/api3dao/api3-docs

Waiting for the docs to be added to api3.org for this.

Weird members/overview URL

Copy-pasting from YEET on Discord:

https://docs.api3.org/pre-alpha/members/#frontmatter-title should be https://docs.api3.org/pre-alpha/members/#overview for the sake of url consistency. Changing the h1 tag id would do I think.

Add api Test Calls doc

See Airnode Issue 468. Need doc to detail the API/Airnode test calls.

OIS api-integration.md for /next

Clone api-integration.md (for /next) and work on a side-by-side comparison to the older (pre-alpha) api-integration.md. Add diagrams and smooth out the content.

Change “cryptocurrency-free” > "not requiring buying or holding of any cryptocurrency"

Change in the docs where relevant (changing “cryptocurrency-free” or similar to “not requiring buying or holding of any cryptocurrency”).

Document allowed OIS titles

Some restrictions will be applied to OIS titles
api3dao/airnode#293
These need to be added to the docs, similar to
https://github.com/api3dao/api3-docs/blame/1ee970633eff63d6d0250cae9703c3d2d971970a/docs/next/technology/deployment-files/config-json.md#L233

Tutorials Per API Partner

This suggestion cae from the forum.

user: telecomsxchange
I think it would be useful to partners to have a tutorial section in the API3 developer docs where each partner can write up a tutorial on a use case of their choice. This would be great for API3 SEO ranking and for Partners to easily link developers to that article for quick start.

See Tutorials Per API Partner from the API3 forum.

Check for unused classes in VersionsModal.vue

These classes are declared in the VersionsModal.vue template but not in the component's styles. Remove them if not in use.

OIS Security Key needs improvement

Currently, the api-integration.md (OIS) file pushed the user to an OAS web page to learn how to add security to an OIS object. It may be better to try and explain security in line.

Deployer image instructions confusing

The instructions to deploy Airnode using a Docker image are confusing. Of course, for /next, a major rewrite is needed but a short intro to pre-alpha would help. It does not even mention which repo to work from.

Jump-start the role API3 Members content

For version 0.1.0. The new role for API3 Members needs to be started with mostly simplified content from the API3 Whitepaper. Once the role (group) has some teeth behind it a review is needed to see what other content should be added or blended in.

Integration DPF.docx

The integration team has a PDF for API providers. Need to add reference to this doc and possibly help to improve it.

Integration DPF.docx

[OIS Specification] fixedOperationParameters not really optional

The OIS specification claims that fixedOperationParameters is optional, but in reality it's not. What is optional is whether it contains any elements in its array.

Either the specification should clarify it by claiming it's required but don't need any child elements, or the airnode code should first check its existence before doing a reduce.

Net revenue of API3 tokens to be burned

A discussion needs to begin on whether the use of the phrase net revenue is correct. See dao-pool.md/Rewards and Risks, first paragraph.

To align the governance incentives with API3’s success, combined with the inflationary rewards, the net revenue to the DAO will result in the burning of API3 tokens.

Should it be:

• gross revenue
• net revenue
• revenue

The concern is over the tokens from revenue used to pay the API providers (tokens used to transfer USDC or monies to API providers). Aren't these tokens thus burned in principle as a result of the payout?

Clarify how the ENS names work for DAO proposals

We now support ENS names (instead of addresses) while making proposals

https://forum.api3.org/t/dao-dashboard-update-august-16-2021/497

There is a potential pitfall here:

• Someone buys an ENS name, makes a proposal with it
• While the proposal is active, they point their ENS name to another address
• The proposal passes. They expect to receive the funds to the new address, but they will receive them at the old address

So what happens is that while making the proposal, the dashboard looks up what address the ENS name is pointing to, and hardcodes that in the proposal on-chain. After that point, the contracts don't care about what you do with your ENS name.

Add reserved parameters docs

See title.

https://github.com/api3dao/api3-docs/blob/master/airnode/reserved-parameters.md

Code overlay need

Often in the docs the user is pushed to code in another location, mainly because the code is too large to show inline. An overlay with a large close button would keep the user in place while viewing this code or other example related content to the main content of the page the user is viewing

OIS Reserved Parameters

The Reserved Parameters section in api-integration.md needs better user guidance.

Add Airnode Heartbest doc

See Airnode Issue 465. Need to add a doc on the Airnode Heaqrtbeat.

Todo Component

It has become difficult to add comments to the docs about things that need updating and items needing research. A new inline Todo Vue component might be useful.

If a page has one or more Todos then a badge will appear on the top right of the page (fixed). The Todos on the page would have a link to a Github Issue (optional). A Github Issue could have a link taking the user into the docs page with the Todo.

Specify environment variable name limitations

envName fields under environment can only include uppercase, numerical or _. https://github.com/api3dao/api3-docs/blob/main/docs/next/technology/deployment-files/config-json.md#environment should be updated to reflect this.

Add more warnings about designated wallets

The designated wallets are custodial, meaning that the requesters should be keeping only as much ETH as they trust the provider with.
Add more warning about this, refer to this example when it's implemented.

Create walkthrough videos for running the node in the cloud

Consider:

• First time deployment
• After first time deployment.

Create walkthrough videos for airnode-starter

Possible videos

Back in the spring timeframe @bbenligiray had asked about creating (3) videos. This issue serves to hold onto the idea until we can decide to move forward. The original issues (#48 #49 #50) have been closed and consolidated here.

• Create walkthrough videos for running the node in the cloud documentation
• Create walkthrough videos for running the node locally documentation
• Create walkthrough videos for airnode-starter documentation

It's not clear what the `in` field for POST operation parameters should be

Received this Discord question (to which the answer is yes)

How to configure config.json for post request? Should I include body as query parameter?

OpenAPI tooling that I had been using had the body parameters of POST operations defined as in: query (and it works just fine for application/json content type that is not nested, which is all we do anyway). After looking it up,I found out that body parameters are in fact defined in a requestBody object, so the way we go is actually quite non-standard. This needs to be documented, i.e., it should say "If you are integrating a POST operation, define the body parameters with in: query. Note that only non-nested application/json content-type is supported." We should also probably consider updating OIS to conform to OpenAPI better here.

Conflicting receipt.json file

There are 2 examples of receipt.json in the docs and they do not seem to match well. Guessing the airnode-starter is outdated since the repo is in need of an update.

In API Provider role: receipt.json

In Reference section: receipt.json

Links for sections don't work

In many places, like the OIS specification, there are lists of links to different parameters. Those links do not work, reason being that the ID generated for the anchors on the page requires an underline and they're case-sensitive.

In other words, the link points to #1-oisFormat but the ID of the anchor is #_1-oisformat.

Test VuePress v2

VuePress v2 is out. Try and migrate to see what breaks and what works. Push to a test site.

Medium post list is outdated

Non-partnership Medium posts should be added to the list regularly. I'm not sure what the workflow for this should be.

Document that if method is POST, query parameters go into body

In OAS, specifying a request body is pretty cumbersome because it needs to be flexible.

In OIS, we only support a non-nested JSON as a body, so body parameters are specified similarly to query parameters. As a result, here, if the method is POST and the in value is query, the parameter goes into the body. This needs to be specified because some users are confused about how they should be specifying body parameters for POST requests and there is nothing in the docs about that.