Dendra Release 3 APIs

Dendra Release 3 provides a set of RPC-based APIs that are accessed over standard HTTP endpoints or gRPC. There are currently two APIs in Release 3:

Our schemas are maintained in .proto files, which are compiled to various launguages (e.g. Python, JavaScript, Go) to enable type-safe access to model objects and request/response bodies.

Users and applications can make calls to Release 3 APIs over standard HTTP endpoints using JSON (via Connect) or through a gRPC client.

We publish our schemas to the Buf Schema Registry, where you can explore types and generate typed clients for a variety of languages. Generated clients improve developer ergonomics and can improve performance with efficient protobuf serialization.

Dendra Science Repositories on the Buf Schema Registry

Protocol Buffers Overview

Protocol Buffers (protobuf) are a language-neutral, platform-neutral mechanism for serializing structured data. They are smaller and faster than JSON while generating native language bindings from a simple schema definition (.proto files).

We chose Protocol Buffers for our Release 3 APIs because they deliver compact binary storage and fast parsing for high-volume data, strong schema evolution, and type-safe generated code across multiple languages.

RPC API Overview

Release 3 APIs use RPC-oriented services instead of REST resource URLs. API calls are handled by Connect, which is a library for building web-friendly and gRPC-compatible HTTP APIs. Clients invoke well-defined requests (e.g. ListOrganizations) using plain HTTP POST methods with JSON payloads.

Some basic principles of RPC are:

Services are groups of RPC methods (for example OrganizationService with ListOrganizations) declared in .proto files.
Requests and responses are Protocol Buffer messages, or strongly typed schemas, as opposed to unstructured JSON payloads.
A typical operation is stateless per call. Each request carries what it needs, though streaming may be available for specific methods.

How to Make a Request

To make a request, you need to know the service and RPC method you want to call.

For example, to list all organizations, you would use the POST method and the URL https://svcs.dendra.science/api/rpc/dendra.api.metadata.v3alpha1.OrganizationService/ListOrganizations.

The response would be the JSON representation of a list of all organizations.

Example: List Organizations

Request:

curl \
    --header 'Content-Type: application/json' \
    --data '{"pageSize": 5}' \
    https://svcs.dendra.science/api/rpc/dendra.api.metadata.v3alpha1.OrganizationService/ListOrganizations

Response:

{
  "nextPageToken": "",
  "organizations":
  [
    {
      "id": "5b032fe439e58256b546331c",
      "name": "UC Nature Research",
      "slug": "ucnatres"
    },
    ...
  ]
}

Example: Get an Organization by ID

Request:

curl \
    --header 'Content-Type: application/json' \
    --data '{"organizationId": "5b032fe439e58256b546331c"}' \
    https://svcs.dendra.science/api/rpc/dendra.api.metadata.v3alpha1.OrganizationService/GetOrganization

Response:

{
  "organization": {
    "id": "5b032fe439e58256b546331c",
    "name": "UC Nature Research",
    "slug": "ucnatres",
    ...
  }
}

Where to Make Requests

The target servers and SDKs for each API can be found at:

API	Target URL	SDKs
Platform API	`https://svcs.dendra.science/api/rpc/`	dendrascience/api
Job API	`https://svcs.dendra.science/job/rpc/`	dendrascience/job

Follow the link below for an example with a pre-filled request body. Hit Send to try it yourself.

Buf Studio: OrganizationService.ListOrganizations