An API is the boundary that lets one software component request work from another without directly operating its internals. In an orchestrator, the manager API accepts developer requests, while the worker API lets the manager start work, stop it, and inspect worker state across the network. section 1.6 section 5.0
A web API exposes that boundary through HTTP. Its small working model is explicit: an HTTP server receives requests; routes describe URL patterns; a router matches requests to routes; and handlers process requests and write responses. The API performs request and response work, then hands task operations to the worker rather than performing the work itself. section 5.1 section 5.7
A task API can make three operations available through resource-oriented routes:
- GET /tasks returns the current task list. section 5.1
- POST /tasks accepts a JSON task request and creates a task. section 8.3
- DELETE /tasks/{taskID} stops the identified task. section 8.3
Parameterized routes carry identifiers in the path. For example, /tasks/{taskID} matches a different task ID on each request, allowing a handler to locate the target task. A handler receives Go's http.ResponseWriter and http.Request, decodes JSON input where needed, delegates to the worker, and returns an HTTP status and response data. section 5.1 section 5.4
Figure 5.2 Internally, the worker’s API is composed of an HTTP server from the Go standard library; the routes, router, and handlers from the chi package; and, finally, our own worker.
This layer diagram makes the separation visible: the standard HTTP server receives traffic, chi supplies routes and routing, handlers adapt requests, and the worker retains the operational logic. section 5.1
Starting, listing, and stopping a task
A developer sends JSON with POST /tasks to the manager and receives 201 Created. GET /tasks returns 200 with JSON task data. DELETE /tasks/{taskID} returns 204 after requesting the task stop. The manager receives the developer-facing request and coordinates with the worker-facing API. section 8.3 section 8.8
Separate APIs serve different callers while preserving the same basic shape. The manager API is user-facing: it starts, stops, and lists tasks for developers. The worker API is internal-facing: it accepts work from the manager and exposes task and metric information. Keeping both APIs on JSON minimizes format translation between components. section 1.7 section 8.0 section 8.3
This design turns running an application into a network request rather than a direct interaction with scheduling, workers, containers, or underlying infrastructure. The same approach is implemented with plain Go handlers, the standard HTTP server, and the lightweight chi router instead of a full web framework. section 1.7 section 8.1
