RPCs - OpenAPI reference

RPCs - OpenAPI reference#

OpenAPI is a specification format for REST APIs. This format is supported by several tools, such as Swagger UI which allows you to browse a specification and perform API calls from your browser. Several code generators also exist to generate API libraries for various programming languages.

Octez Node#

The REST API served by the Octez node on the RPC port is described by the union of several OpenAPI specifications:

  • rpc-openapi(-rc).json, containing the protocol-independent (or “shell”) RPCs in the last (candidate) release

  • rpc-openapi-dev.json, containing the protocol-independent (or “shell”) RPCs in the current development version (branch master)

  • For each protocol in use:

    • $PROTOCOL-openapi.json (served under the prefix: /chains/<chain-id>/blocks/<block-id>)

    • $PROTOCOL-mempool-openapi.json (served under the prefix: /chains/<chain-id>/mempool)

For instance, for an RPC listed as GET /filter in $PROTOCOL-mempool-openapi.json, its real endpoint is GET /chains/<chain-id>/mempool/filter.

These OpenAPI specifications, detailed below, can be generated by running the Octez node as shown in section How to Generate. For convenience, the files generated from the most recent release(s) are provided in this page, annotated each time with the corresponding release (in parentheses).

Note

There exists an alternative reference for the node RPCs, presented in more static pages (e.g. Rio RPCs - Reference for the active protocol). However, the static referece omits some RPCs, such as the ones related to the mempool.

Shell RPCs#

The node provides some RPCs which are independent of the protocol. Their OpenAPI specification can be found at:

Rio RPCs#

The OpenAPI specifications for RPCs which are specific to the Rio (PsRiotum) protocol can be found at:

The OpenAPI specifications for RPCs which are related to the mempool and specific to the Rio protocol can be found at:

Seoul RPCs#

The OpenAPI specifications for RPCs which are specific to the Seoul (PtSeouLo) protocol proposal can be found at:

The OpenAPI specifications for RPCs which are related to the mempool and specific to the Seoul protocol proposal can be found at:

Alpha RPCs#

The OpenAPI specifications for RPCs which are specific to the Alpha protocol can be found at:

The OpenAPI specifications for RPCs which are related to the mempool and specific to the Alpha protocol can be found at:

Smart Rollup Node#

The smart rollup node exposes different RPCs depending on the underlying L1 protocol in use. Their specification is given in the sections below. (The exact versions of the rollup node for which these files are produced can be seen in the field .info.version within each file.)

Rio RPCs#

The OpenAPI specifications for the RPCs of the smart rollup node for the Rio (PsRiotum) protocol can be found at:

Seoul RPCs#

The OpenAPI specifications for the RPCs of the smart rollup node for the Seoul (PtSeoul) protocol proposal can be found at:

Alpha RPCs#

The OpenAPI specifications for the RPCs of the smart rollup node for the Alpha protocol can be found at:

DAL Node#

The DAL node also provides RPCs. Their OpenAPI specification can be found at:

How to Generate#

To regenerate the *-dev.json and alpha-*.json files above from the current sources in your Octez repository, run make -C docs openapi from the root of the Octez repository, which will run the generation script and check if the JSON files above are up-to-date with respect to their versions under Git (modulo the version fields inside). If there are any significant differences, it will also render the corresponding JSON files as HTML.

Note that:

  • The generation script src/bin_openapi/generate.sh requires the Octez executables to be built, so you have to first run make from the repository root.

  • The HTML rendering script docs/scripts/openapi2html.sh requires yq and redocly to be installed.

For platform contributors: if you want to update the OpenAPI and HTML files in the official repository and documentation, you may create a merge request to update the changed files under docs/api/.

Instead of executing all at once with the makefile, you may execute manually the generation or rendering, as follows.

OpenAPI generation#

The OpenAPI generation script src/bin_openapi/generate.sh must be run from the root of the Octez repository.

The generation script will start a sandbox node, activate the protocol, get the RPC specifications from this node and convert them to OpenAPI specifications.

To generate the OpenAPI specification for the RPCs provided by a specific protocol instead of Alpha, update the following variables in src/bin_openapi/generate.sh:

`sh protocol_hash=ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK protocol_parameters=src/proto_alpha/parameters/sandbox-parameters.json protocol_name=alpha `

For protocol_hash, use the value defined in TEZOS_PROTOCOL.

HTML rendering#

For generated OpenAPI files that changed, you may derive the corresponding statically-rendered HTML pages, typically using:

docs/scripts/openapi2html.sh docs/api/*.json

How to Test#

You can test OpenAPI specifications using Swagger Editor to check for syntax issues (just copy-paste rpc-openapi.json into it or open it from menu File > Import file).

You can run Swagger UI to get an interface to browse the API (replace xxxxxx with the directory where rpc-openapi.json is, and rpc-openapi.json by the file you want to browse):

docker pull swaggerapi/swagger-ui
docker run -p 8080:8080 -e SWAGGER_JSON=/mnt/rpc-openapi.json -v xxxxxx:/mnt swaggerapi/swagger-ui

Then open it in your browser.