API Setup

The API setup is where you can define your endpoints and the parameters associated with them.

Add your endpoints and parameters

17801780

Go to the Reference Docs tab and add a page like you normally would. On the top-left, there is a dropdown button. This will let you select the type of page you want, select API endpoint to bring up the API builder.

After that, describe your API's URL and parameters, then optionally add a response example or two. Be sure to add all the necessary params in your endpoint description. You have the option of adding path, query, body, or header params here.

Lastly you can select if you want authentication enabled or disabled for this endpoint.

If ":param" is found in your URL, it will be replaced. So, something like http://test.com/item/:id?color=:color would become http://test.com/item/123?color=red.

If not, it will either be appended as a query string (if the endpoint method is GET) or posted based on the "Content-Type" in API explorer (if anything other method type).

🚧

Endpoint Methods and Paths Must Be Unique

Please note that due to limitations with the OpenAPI Specification that powers our API reference, we do not support the creation of multiple API endpoint pages that have the same HTTP method and path. As a workaround, you can do one of the following:

  1. Create separate API definitions that use the same base URL and associate your endpoints with different API definitions
  2. Within the same API definition, use hash parameters in the endpoint URL to distinguish the two endpoints (e.g. /endpoint#one, /endpoint#two)

Required Parameters

Path parameters will always be required, but for query, body, and header they will be optional by default. However if you click on the star next to the parameter, it will make it required.

Object definitions

14541454

You can add object schemas that can be reused across endpoints by selecting object/hash and clicking on manage definitions. It will take you to our object wizard, which lets you add the parameters of the object schema.

14241424

📘

Nested Object Parameters

Tip: You can do nested object params by using either dot notation (user.id) or bracket notation (user[id]).

Test It Out!

You should be ready to go! Visit your page, and play around with the API Explorer. Every API is unique; let us know if something doesn't work and we'll do what we can to fix it!


Did this page help you?