Skip to main content

An API reference that cannot go stale, and a layout for wide screens

CoRelayer
CoRelayer
Cooperative Relayer Infrastructure for Autonomous Transactions

The API reference is now rebuilt from scratch on every build and checked page by page against the API document. On a desktop screen or wider, an operation page puts the description and the request samples side by side. On a 2560 px screen, guide pages get a rail beside the article: the page's contents and the errors it links to.

The reference is always regenerated​

The reference is generated by docusaurus-plugin-openapi-docs. That plugin only writes a page if no file of that name exists yet. So far the build ran it over the pages it had written before. An edit to openapi.yaml would have kept the old pages, and nothing would have failed. The build now empties the reference folder first.

A new test also decodes the operation embedded in every generated page and compares it with openapi.yaml:

  • there is one page per operation and webhook, and no page for an operation the document no longer has;
  • each page has the operation's method, path, summary, description, tags, parameters and response codes;
  • each schema has a page, and the reference names the version of the document it was built from.

Operation pages by screen width​

The description and the samples of an operation page used to share the 760 px column meant for prose. That column is now the limit for each panel on its own:

ScreenLayout
Below 1536 pxThe description, then the request and response samples below it.
1536 px and upNavigation, description and samples side by side. The samples stay in view while you scroll the description.
2560 px and upThe same three columns, with the extra width given to the samples.

The request samples come in curl, JavaScript (fetch), Python (Requests) and Rust (reqwest): curl, plus the three languages the SDK guides cover.

A rail on very wide screens​

At 2560 px and wider, a guide page keeps its 760 px article. Beside it is a rail that stays in place as you scroll, with two parts:

  • On this page: the page's headings.
  • Related errors: each error code the page links to, with its HTTP status.

The error list is built from the page's own links, so it always matches the text. Narrower screens do not show the rail.

Status page brought up to date​

Status and SLOs lists what is built but not proven. Three of its lines were out of date:

  • The allocator that gives each API host its share of an account's cap is now written.
  • Inclusion tracking now has all three of its sources wired.
  • Pay-as-you-go settlement now runs end to end in a test.

Each line now says what the backend's tests prove and what they do not. All three are tested only against stand-ins for the database and the chain. Their tests against a real database have not yet been seen passing.

Found while checking​

  • Two layout rules for phones and ultrawide screens matched no element, so neither had any effect. They are fixed. The ultrawide rules also started at 2200 px instead of the 2560 px where that layout class begins.
  • Some operation descriptions in the API document mention internal specification sections, such as "relay-intent.md section 10.6". The reference shows the document as it is. The wording has to be changed in the API document itself, not in the reference.