Endpoints and definitions

The Definitions section describes every endpoint of your API. This is what powers your public endpoint pages, the playground, the code snippets and the gateway's routing. The gateway only forwards calls to endpoints defined here; any other path is rejected with 404 ENDPOINT_NOT_FOUND, so consumers can't probe routes you haven't published.

Endpoints and groups

• Click Add endpoint to create one.
• Create groups (for example "Orders" or "Payments") with an optional description to organise larger APIs.
• Drag endpoints and groups to change their order, or use Move to group. The order here is the order on your public listing.
• Use the search box to find an endpoint.

Editing an endpoint

Details

• Name: a short title ("Get current weather").
• Description: what it does, with Markdown supported.
• External doc URL / description: an optional link to further reading.
• Requires authentication: leave on for normal endpoints.

Request

• Method (GET, POST, PUT, PATCH, DELETE…) and Path. Use curly braces for path parameters: /v1/users/{userId}.
• Parent group.
• Parameters: header, query and path parameters. For each one, set the name, type, a default or example value, whether it's required, and a description. The example value pre-fills the playground.

Body

For endpoints that take a body, choose the media type:

• application/json (and other raw types such as XML or text): add one or more named example bodies. A JSON schema is generated from your example, and you can edit it.
• multipart/form-data, x-www-form-urlencoded or octet-stream: describe the body as a table of fields (name, type, required, example, description), for example a file field for uploads.

Add a body description to explain anything the examples don't.

Responses

Add one entry per status code the endpoint can return: 200 for success and 400, 404 and so on for errors. Each response has a media type, a description, a schema, and one or more named examples (with the headers seen with that example). Generate schema builds the schema from an example, and Generate example does the reverse.

Good responses make a big difference: developers decide whether to subscribe by reading them.

Test endpoint

At the bottom of the editor, Test endpoint sends a real request straight to your base URL (not through the gateway), so it works even before you publish. Adjust the parameters and click Send request. When the response looks right, click Save as example to add it to the endpoint's documented responses. Changes you make in the test panel only affect that test run.

Versions

Use the version switcher to manage versions of your API (for example 1.0.0 and 2.0.0). You can create a new version, duplicate an existing one as a starting point, and mark versions as draft, active or deprecated. Your listing shows the current version's endpoints.