This document proposes the argument and proposal for redesigning the external Bacalhau API.

Introduction

The Bacalhau server API (referred to as just “the API” from now on) is the publicly-facing interface to interact with the Bacalhau network. It exposes the functionality of the “Requester node” but the implementation details are not relevant to this discussion.

This document does not consider the “GossipSub” API to be part of the public API because it is not meant to be consumed by users.

Challenges

Bacalhau has always been developed with a client-server pattern in mind. Users interact with the Bacalhau network via the API but historically this has been using a binary that is colocated with the server codebase.

More recently, we’ve been looking at adding other ways to interact with the API, via SDKs, for example. We’ve also been thinking about improving the monitoring and that has brought up some issues with the API.

But the greatest issue is that the API was never designed. It grew organically from the procedural code developed in the server codebase. The “REST API” is not entirely resource based, it’s largely procedural, and some Bacalhau resources (like jobs, for example) are not idempotent, content addressable or consistent.

Furthermore, as we increase the efforts into creating clients in different languages (e.g. python, js, etc.), the need to clearly separate the server from the client-side logic (e.g. config init, request signing, the system package) becomes more compelling.

Therefore, we propose that we redesign the API’s from scratch to fulfil the needs of the clients and implement best practices.

Requirements

Functional Requirements

• All resources should be content addressable — i.e. IDs are actually CIDs. This allows for automated caching. If a job with that ID already exists, you don’t need to create another one.
• Resources should adhere to the CRUD principles, exposing precise functionalities (e.g. GET /job-results shall download directly the results without the need for the client to work out what and where to get them from).

Design

Currently, there’s a lot of debug cruft in the Bacalhau server API. I’m trying to ignore that and focus on the user-specific use cases.

Use Cases

As a user of the bacalhau public API (NOT the CLI)…

• I want to filter jobstatus’ for the jobs I am interested in