Controllers, actions, and routes

A controller gives related APIs a shared path. Each action adds a route, an HTTP method, and a workflow. Together they determine which graph handles a request.

Read a Cloudgate URL#

https://YOUR-API-HOST/sbx/orders/status
                       └┬┘ └─┬──┘ └─┬──┘
                  environment │     action route
                         controller path

For this example, set the controller path to orders and the action route to status. The action route is relative: do not include the environment prefix or controller path.

The method participates in routing. A GET and a POST at the same path can resolve to different actions. A correct URL with the wrong method can return an endpoint-not-found response.

Create and organize actions#

1. Open Workflows → Controllers and create or select a controller.
2. Give it a stable, descriptive path such as orders or inventory.
3. Create actions for individual operations and select their request methods.
4. Configure response format and access rules, then open each action in the Flow Builder.

Use names that describe behavior: List orders, Get order, or Create order. Keep related actions together, and avoid renaming public routes without planning for existing clients.

Capture a route value#

An action route can contain a selector placeholder:

${orderId}/status

A request to /sbx/orders/123/status makes orderId available to the workflow. Validate its format and authorize access to the record before using it.

Manage changes#

Edit a draft when changing a published action. Review routes, methods, access rules, and graph changes together before releasing. A controller export is useful for reuse or recovery, but imported selectors, databases, and external credentials still need review in the destination.

See templates and imports, request data, and releases.