Modifying HTTP Endpoints
Developmentmodifying-http-endpointsModifying HTTP Endpoints is an Agent Skill for development published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/modifying-http-endpoints/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/modifying-http-endpoints, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Modifying HTTP Endpoints
Framework
Golem uses Poem with poem-openapi for REST API endpoints. Endpoints are defined as methods on API structs annotated with #[OpenApi] and #[oai].
Where Endpoints Live
- Worker service:
golem-worker-service/src/api/— worker lifecycle, invocation, oplog - Registry service:
golem-registry-service/src/api/— components, environments, deployments, plugins, accounts
Each service has an api/mod.rs that defines an Apis type tuple and a make_open_api_service function combining all API structs.
Adding a New Endpoint
1. Define the endpoint method
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>> {
// ...
}
2. If adding a new API struct
- Create a new file in the service's
api/directory - Define a struct and impl block with
#[OpenApi(prefix_path = "/v1/...", tag = ApiTags::...)] - Add it to the
Apistype tuple inapi/mod.rs - Instantiate it in
make_open_api_service
3. Request/response types
- Define types in
golem-common/src/model/withpoem_openapi::Objectderive - If the type is used in the generated client, add it to the type mapping in
golem-client/build.rs
After Modifying Endpoints
After any endpoint change, you must regenerate and rebuild:
Step 1: Regenerate OpenAPI specs
cargo make generate-openapi
This builds the services, dumps their OpenAPI YAML, merges them, stores the result in openapi/, and regenerates the public REST API reference under docs/src/content/rest-api/*.mdx (used by the learn.golem.cloud site). Commit both the updated openapi/*.yaml and the updated docs/src/content/rest-api/*.mdx — CI's check-openapi task will fail otherwise.
If the in-tree YAML is already up to date and you just need to refresh the docs (e.g., after editing docs/openapi/gen-openapi.ts itself), use cargo make generate-docs-openapi to skip the service rebuild.
Step 2: Clean and rebuild golem-client
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.
Step 3: If new types are used in the client
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.
Step 4: Build and verify
cargo make build
Then run the appropriate tests:
- HTTP API tests:
cargo make api-tests-http - gRPC API tests:
cargo make api-tests-grpc
Checklist
- Endpoint method added with
#[oai]annotation - New API struct registered in
api/mod.rsApistuple andmake_open_api_service(if applicable) - Request/response types defined in
golem-commonwithpoem_openapi::Object - Type mappings added in
golem-client/build.rs(if applicable) cargo make generate-openapirun — staged changes include bothopenapi/*.yamlanddocs/src/content/rest-api/*.mdxcargo clean -p golem-client && cargo build -p golem-clientruncargo make buildsucceedscargo make fixrun before PR