Skip to main content

API Design Guidelines

  1. Top-Level Categories

Group endpoints by functional domain. Each domain gets its own top-level path prefix (e.g., /node/, /job/, /health/). Avoid nesting unrelated operations under a shared prefix.

  1. Resource-Oriented Paths

Use nouns for resources and let HTTP methods convey the action. Sub-resources should be nested under their parent (e.g., /node/{hostname}/network/dns/{interfaceName}).

  1. Consistent Verb Mapping
  • GET — Read or list resources
  • POST — Create a resource or trigger an action
  • PUT — Replace or update a resource
  • DELETE — Remove a resource
  1. Scalability and Future Needs

If an area is expected to grow in complexity with more endpoints, separate it into its own top-level category early — even if it only has a few operations today. This avoids clutter and keeps each domain cohesive.

  1. Node as Top-Level Resource

All operations that target a managed machine are nested under /node/{hostname}. The {hostname} path segment identifies the target and accepts literal hostnames, reserved routing values (_any, _all), or label selectors (key:value).

Sub-resources represent distinct capabilities of the node. Examples of the nesting patterns used:

PatternExample
/node/{hostname}Node status
/node/{hostname}/{resource}disk, ntp
/node/{hostname}/{resource}/{id}sysctl/{key}
/node/{hostname}/{domain}/{resource}network/dns
/node/{hostname}/{domain}/{resource}/{id}user/{name}
/node/{hostname}/{domain}/{resource}/{id}/{action}service/{name}/start

Browse the combined OpenAPI spec (internal/controller/api/gen/api.yaml) or the Docusaurus API reference for the full endpoint list.

  1. Path Parameters Over Query Parameters

Use path parameters for resource identification and targeting. Use query parameters only for filtering and pagination on collection endpoints (e.g., /job?status=completed&limit=20).

Never use query parameters to identify which resource to act on. Complex input data belongs in request bodies.