REST API Reference

We use protobuf to define language-agnostic message structures. We use these type definitions with gRPC-gateway to provide consistent REST endpoints to serve various needs.

Using these two tools we also auto-generate OpenAPI v2 spec (aka Swagger RESTful API Documentation Specification) which lets us inline documentation for each endpoint and response in our codebase.

Having this specification prepared we can serve it to different tools to generate code for different languages (eg swagger codegen) as well as provide web-based explorers into our APIs (e.g., Swagger UI).

Swagger UI

As Swagger puts it:

“Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client-side consumption.”

A static version of the Swagger UI is bundled with these docs here. If you have access to a running Determined cluster you can checkout the live-interact version by clicking the API icon from the Determined WebUI or by visiting the path /docs/rest-api/ on your Determined cluster.

The Swagger UI gives you an up-to-date view of the APIs your Determined cluster provides in a readable and interactive fashion.

On this page, you’ll see a list of all the available endpoints grouped by their workflows. If you click on each endpoint you’ll be presented with expected inputs and outputs for it as well as an interactive tool that lets you try out the endpoint. Note that for the interactive portion to work, you’d need to have the appropriate cookie set and have a running cluster. To set up the authentication take a look at the authentication section below or simply log in through the WebUI.