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.

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

  • 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. Nairobi RPCs - Reference for the active protocol). However, the static referece omits some RPCs, such as the ones related to the mempool.

Warning

The links below to the different OpenAPI specifications are opened using the Swagger UI integrated in GitLab. This UI can be used for browsing the OpenAPIs (no need to install Swagger UI for that). However, the interactive use suggested in this UI does not currently work because:

  • the UI does not allow one to specify a server (which should correspond to a runnning Tezos node), and

  • browsers may block some of the generated requests or responses for security issues.

Shell RPCs

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

Oxford RPCs

The OpenAPI specification for RPCs which are specific to the Oxford (Proxford) protocol can be found at:

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

Nairobi RPCs

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

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

How to Generate

To generate the above files, run the src/bin_openapi/generate.sh script from the root of the Octez repository. It 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, 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.

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.