Adding or modifying HTTP REST API endpoints in Golem services. Use when creating new endpoints, changing existing API routes, or updating request/response types for the Golem REST API.
Golem uses Poem with poem-openapi for REST API endpoints. Endpoints are defined as methods on API structs annotated with #[OpenApi] and #[oai].
golem-worker-service/src/api/ — worker lifecycle, invocation, oploggolem-registry-service/src/api/ — components, environments, deployments, plugins, accountsEach service has an api/mod.rs that defines an Apis type tuple and a make_open_api_service function combining all API structs.
Add a method to the appropriate API struct (e.g., WorkerApi, ComponentsApi):
#[oai(
path = "/:component_id/workers/:worker_name/my-action",
method = "post",
operation_id = "my_action"
)]
async fn my_action(
&self,
component_id: Path<ComponentId>,
worker_name: Path<String>,
request: Json<MyRequest>,
token: GolemSecurityScheme,
) -> Result<Json<MyResponse>> {
// ...
}
api/ directory#[OpenApi(prefix_path = "/v1/...", tag = ApiTags::...)]Apis type tuple in api/mod.rsmake_open_api_servicegolem-common/src/model/ with poem_openapi::Object derivegolem-client/build.rsAfter any endpoint change, you must regenerate and rebuild:
cargo make generate-openapi
This builds the services, dumps their OpenAPI YAML, merges them, and stores the result in openapi/.
The golem-client crate auto-generates its code from the OpenAPI spec at build time via build.rs. After regenerating the specs:
cargo clean -p golem-client
cargo build -p golem-client
The clean step is necessary because the build script uses rerun-if-changed on the YAML file, but cargo may cache stale generated code.
Add type mappings in golem-client/build.rs to the gen() call's type replacement list. This maps OpenAPI schema names to existing Rust types from golem-common or golem-wasm.
cargo make build
Then run the appropriate tests:
cargo make api-tests-httpcargo make api-tests-grpc#[oai] annotationapi/mod.rs Apis tuple and make_open_api_service (if applicable)golem-common with poem_openapi::Objectgolem-client/build.rs (if applicable)cargo make generate-openapi runcargo clean -p golem-client && cargo build -p golem-client runcargo make build succeedscargo make fix run before PR