Endpoints

The next step in the process is to start defining your API endpoints. This is how developers will know what endpoints they have available to them as well as all of the parameters they can use.

Create an API endpoint

To create a REST endpoint:

1. Click My APIs in the header to view the Provider Dashboard.
2. In the sidebar, click the Definition tab for your API.
3. Click API Specs in the second level header.
4. Click Endpoints in the third level header.
5. Click Create REST Endpoint.

The following page will then appear:

This page is where you can define all of the following functionality:

Name: You can provide a descriptive name for the endpoint or just set the name to match the route. This will be the name visualized in the quick menu on the right-hand side of the Documentation explorer
Description: This helps developers understand what the endpoint does.
External Doc URL: External link to more information on the endpoint.
External Doc Description: Brief label for the External Doc URL link.
Method: This is the unlabeled dropdown. Defines the HTTP method that will be used to call your endpoint. RapidAPI supports GET, POST, PUT, DELETE, and PATCH.
Path: This is the textbox to the right of the method dropdown. This specifies the route to the endpoint. This path does not including your Base URL. In some cases, you might want to allow the user to specify a parameter in the route (a path parameter), therefore, you can use curly braces to encapsulate the user-defined parameter. For example, if a path of “/status/{appid}” is specified, an additional parameter input box will be created for the user to specify the parameter’s value when testing the endpoint.

🚧

Reserved endpoint path names

There are several API endpoint path names that are currently reserved for RapidAPI, please avoid using these path names:

• /ping
• /_test
• /_transform
• /500.json
• /robots.txt

API Groups

API groups are used to visualize similar API endpoints together, allowing developers to find endpoints faster.

Once you have created one or more endpoints, you can create API groups and organize the endpoints within the group.

To create an API group (assuming you have created at least one endpoint):

1. Click My APIs in the header to view the Provider Dashboard.
2. In the sidebar, click the Definition tab for your API.
3. Click API Specs in the second level header.
4. Click Endpoints in the third level header.
5. Click Create Group. You will then see a dialog where you enter the group name, brief description of the group, and can provide a link to an external documentation URL.

Groups and endpoints can be arranged by dragging and dropping them in the Endpoints list. They can also be edited by clicking the associated edit link.

Request headers

You can specify custom headers to be passed to your API endpoint by the user. To add a header, navigate to the Header tab on the Add Endpoint screen.

You can provide the following information for request headers:

Name: A name is required for your header parameter.
Value: A value can be pre-filled into the header parameter to be displayed on the RapidAPI Hub when users test the endpoint.
Type: Choose from String, Enum, Number, Boolean, Date, Time or Geopoint.
Required: Check this box to make the header string parameter required.
Description: Describe the parameter in a few words.

Query string parameters

Adding a query string parameter can be used to add additional parameters to a request. For example, a filter (imagine “?limit” or “?offset”) could be an additional query string parameter passed with the request. To add a query string parameter, navigate to the Query tab on the Add Endpoint screen.

You can provide the following information for query string parameters:

Name: A name is required for your query parameter.
Value: A value can be pre-filled into the query parameter to be displayed on the RapidAPI Hub when users test the endpoint.
Type: Choose from String, Enum, Number, Boolean, Date, Time or Geopoint.
Required: Check this box to make the query string parameter required.
Description: Describe the parameter in a few words.

Body parameters (only for POST, PUT and PATCH)

When you specify the method to query the endpoint as a POST, PUT, or PATCH method, you can also define a payload for the request. You can add it as a form parameter or as a model.

Payload form encoded parameters

A payload defined as a form-encoded parameter is the simplest and recommended way to pass arguments into the payload.

Start by selecting form-data as the media type
Name: A name is required for your form parameter.
Value: A value can be pre-filled into the form parameter to be displayed on the RapidAPI Hub when users test the endpoint.
Type: Choose from String, Enum, Number, Boolean, Date, Time, Object, Array, Geopoint, or Binary.
Required: Check this box to make the form parameter required.
Edit Details: Opens more options to add a description

Other payload media types

With the Media Type selector, you can define a payload in multiple formats which gives consumers the flexibility to post data to your endpoint from an option you make available. You can specify many parameters and create nested objects depending on the media type.

Media Type: Choose from available types: application/json, application/xml, text/plain, application/octet-stream, form-data
Name: A name is required for your form parameter.
Description: Describe the parameter in a few words.
External Link Link to external documentation paired with a description of what the link points to
Example: Fill out an example with a description of what the model looks like. For example, for a JSON model it might be:

{
  "name" : "RapidAPI",
  "text" : "This model always works"
}

Mock responses

Mock responses allow you to develop and test related services and apps while the API itself is still under development.

Enable mock responses

From the Provider Dashboard, navigate to the API's Definition page and select the Endpoints tab. Edit the desired endpoint.

Scroll to the bottom and click the "Mock Response" button. Specify response codes, headers, and response body. Enable mock responses with the slider, and save the endpoint.

📘

You can specify a separate mock response for each endpoint. You can also override an actual response from the API by enabling a mock response for the endpoint.

A developer testing the API on the RapidAPI Hub will see a notification that the endpoint is configured to return a mock response. RapidAPI automatically adds a header "x-rapidapi-mock-response" with the value "true" to each mock response.