API Design

Responses

Responses describe what an endpoint returns for each HTTP status code — the body structure, the content type, the headers, and example payloads. A well-documented set of responses is what turns a bare endpoint into a usable contract.

Defining a response

Each response is keyed by a status code. Routebase pre-fills a sensible description for common codes — "Request successful" for 200, "Resource not found" for 404, and so on — which you can replace with something specific to your API by clicking it.

Field What it is
Status code The HTTP status this response documents. Click the status badge to change it.
Description A short explanation of when this response occurs.
Content type The media type of the body — application/json by default; XML, form, text, and binary types are also available.
Body The structure of the response body, defined inline or referenced from a schema or a reusable response component.
Headers The HTTP headers this response returns.
Example A sample payload shown in your documentation and used by your mock server.
Responses listed by status code

Adding responses quickly

Click Add Response to open the add menu. Besides picking individual codes from three template groups, the Quick Add entry scaffolds a whole set matched to the endpoint's method in one click — for example 200, 401, 403, 404, 500 for a GET endpoint or 201, 400, 401, 403, 409, 500 for a POST. Click the set to customize the selection before adding.

The template groups cover the common families:

  • Success Responses — 200, 201, 204
  • Client Errors — 400, 401, 403, 404, 409, 422
  • Server Errors — 500, 502, 503

With two or more responses defined, use Expand All / Collapse All to manage the list.

Response bodies

Define the body structure directly in the response card's property table, or reference a reusable definition:

  • Inline — add properties with name, type, format, and description right in the response. Inline bodies are fine for one-off shapes.
  • Link a schema — drag a schema from the sidebar onto the response card to link it as the body. The response then shows a schema badge; changing the schema updates every endpoint that references it. See Schemas.
  • Link a response component — drag a reusable response component (for example a shared NotFound error response) onto the responses area to add or replace a response, complete with its body, headers, and example. See Components.

When an inline definition turns out to be reusable, extract it instead of copying: Extract to Component turns the whole response into a reusable response component, and Extract Schema to Component turns just the inline body into a schema — in both cases the endpoint is re-linked to the new definition automatically.

A response body defined from a reusable schema

Response headers

Document the headers your endpoint returns — Location on a 201, rate-limit headers, and so on — in the response's Headers tab. Each header has a Name, a Type (string, integer, number, or boolean), a Required flag, and a Description. Click Add Header to add one inline; headers can also be linked to reusable header components so their definition stays consistent across responses.

Responses can additionally inherit headers from header policies defined at the organization, project, or spec level. Inherited headers are listed beneath your own — group them by level or view them flat — and each one can be overridden locally or excluded from this response; excluded headers can be restored later.

Examples

Every structured response has an Example panel. Routebase generates a realistic sample payload from the body's properties automatically — open the panel and the example fills itself in, with Regenerate to rebuild it after schema changes and Copy to grab it for tests or docs. You can also edit the example freely; it is validated against the schema and used by your mock server.

Deleting a response

Click the delete icon on a response card. The confirmation dialog names the status code and warns that the action cannot be undone.

Permissions

Editing responses requires specs:write (included in the Member role). On a published, locked version the responses section is read-only — create a new version to make changes; see Versioning.