Skip to main content

Network API

Provision and manage blockchain networks via a declarative REST interface.

The Network API is currently in alpha stage and may experience breaking changes. We welcome developers to try out our APIs and share the feedback to us at engineering@bloctopus.io.

Overview​

The Network API is consumes and serves requests using the REST interface: each resource is exposed at a predictable URL and manipulated with standard HTTP verbs.

  • GET retrieves an object (or a list of objects).
  • POST creates a new object.
  • PUT updates a specified object in full.
  • DELETE removes a specified object.

All endpoints return appropriate HTTP status codes (200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, etc.) and JSON payloads, both for successfully responses as well as errors.

Furthermore, the API uses a declarative model: you submit JSON "resource" objects that express what you want (for example, a Network with a specific chain configuration). The API server accepts and persists your object, and background processes continuously reconcile toward your desired state. Progress and health are exposed (where applicable) via a standard status field.

Under the hood, the API server uses open-source Kurtosis packages to spin up blockchain components in a network. For documentation on the specific packages, see Supported chains and plugins.

API objects follow a pattern akin to Kubernetes, but focused on blockchain network provisioning rather than container orchestration.

Base URL​

Throughout the documentation, we assume that you prepend the following base URL to API endpoints to make a well-formed URL.

https://apis.bloctopus.io/network

Authentication​

This API is secured. For more information on authenticating your requests, please see Authentication

Authorization​

Some endpoints managed by this API may subject to authorization. For more information, please see Authorization

Listing, pagination and filtering​

All listing endpoints return typed list objects (for example, NetworkList) that are divided into pages if there are a large number of matching items. The requester may determine the page size (via the limit query parameter), or the API server will return pages once it has parsed a certain accummulated size of items. If there are more results, an opaque string (under metadata.cursor) will be returned alongside the matching items. This string can be included in subsequent list requests (via the cursor query parameter) to fetch the next page of items. Note that some pages may be empty (contain zero item), but a cursor may still be included. In other words, the only way to know if you have reached the end of the list is when no cursor is returned.

For example, you may make a request to return the first 10 networks that you have access to:

GET /v1alpha1/workspaces/{workspace}/networks?limit=10

The server may respond with:

{
  "kind": "NetworkList",
  "version": "v1alpha1",
  "items": [
    {
      "kind": "Network",
      "version": "v1alpha1"
      // ...
    }
    // ...
  ],
  "metadata": {
    "cursor": "some_opaque_string"
  }
}

You can then fetch the next 10 networks with:

GET /v1alpha1/workspaces/{workspace}/networks?limit=10&cursor=some_opaque_string

You must not attempt to interpret this string, it does not have any particular meaning and may have its format changed at any point.

Filtering​

Certain listing endpoints may allow you to provide the query parameter selector to narrow your search criteria. Note that each object type may have a different set of selectable fields, and any fields outside of those specified are not selectable.

The following is an exhastive example of the syntax and supported operators for selectors:

status.state == Operational
status.state IN (Operational, Pending)
status.state != Stopped

Your selector string must be properly URL encoded.

For example, you may list all operational networks that you have access to:

GET /v1beta/workspaces/{workspace}/networks?selector=status.state==Operational

Pagination still applies if there are a large number of matching items.

Error response​

All well-formed API endpoints return an Error object when the server fails to process a request, along with an appropriate HTTP code.

API versioning and depreciation policy​

We will update this section soon.

Reference​