This repository contains the OpenAPI definitions for the Cycle Platform. This spec is used to generate various API clients, used by our team internally, and also the foundation of our API documentation.
The platform API is the general use API for the Cycle Platform, and is available to all Cycle customers. It is the same API consumed by Cycle's portal, and is the main way to interact with all aspects of the platform.
See the platform folder for implementation.
Inside every container running on Cycle, there is a Unix socket mounted at /var/run/cycle/api/api.sock. You can send HTTP requests over this socket to access information about the local environment, access secrets, and much more. The way this internal API functions is very similar to how Cycle's main API works, though the purpose is different. The internal API is primarily used by instances to learn about their environment, and dynamically update as deployments change.
See the internal folder for implementation.
The scheduler API is used to interact with the Scheduler Service inside of an environment on Cycle. The scheduler service can be accessed from other containers in the environment over the private network, or the scheduler service can be made available over the public internet.
See the scheduler folder for implementation.
Cycle's Infrastructure Abstract Layer (IAL) API. Endpoints listed here should be implemented by the customer, and Cycle will call the various endpoints over the lifecycle of provisioning and decommissioning servers.
For more information, check out the official Infrastructure Abstraction Layer Documentation.
While not truly an API spec, the stack spec defines the JSON schema for a Cycle Stack File. The JSON schema is useful for editor validation etc.
The compiled stack spec schema is committed to this repo and hosted on JSON Schema Store
The APIs can be consumed by tools that support stitching together specs divided between multiple files, or built into a single file using the Redocly CLI.
You must have npm installed on your machine, or run inside a container with npm in the PATH.
npm run build:platform
The outputted file is located at /dist/platform.yml
npm run build:internal
The outputted file is located at /dist/internal.yml
npm run build:scheduler
The outputted file is located at /dist/scheduler.yml
npm run build:ial
The outputted file is located at /dist/ial.yml
npm run build:stackspec
This will build the stack spec into a single JSON schema file, and save it to ./stackspec/stackspec.json.
This file should be committed to the repo.
The API specs in this repo are written using the OpenAPI 3.1.0 standard. Some code generators and other tools haven't yet been updated to support 3.1.0, which can be an inconvenience. For us, it seems nearly all golang client generators don't support 3.1.0 (if you find one let us know!).
To resolve this, we've created a script that will downconvert the openapi spec to 3.0.3. Of course, some fidelity is lost with these conversions, so it may not be a perfect 1:1 with the 'true' spec, but hopefully is good enough to generate clients off of when necessary.
To downconvert, run npm run downconvert:platform. The script will output to dist/platform-3.0.3.yml.