The RapidAPI Developer Hub

Welcome to the RapidAPI developer hub. You'll find comprehensive guides and documentation to help you start working with RapidAPI as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

Documenting Your API

API Authentication

RapidAPI automatically gives your API both authentication and user management functionality. For developers consuming your API, this provides a seamless integration experience. RapidAPI is able to authenticate requests for all of their API connections using a single RapidAPI key. To learn more about API Keys on RapidAPI, head over to our docs on API Keys.

Using RapidAPI authentication allows developers to test your API from a browser, subscribe with a single click, and start using your API without the friction of signing up for yet another account, getting API credentials, and setting up API calls with those credentials.

Authentication Flow

Authentication Flow

Since RapidAPI automatically provides authentication and user management, there are two ways that we recommend authenticating requests in your APIs service. 1) Using the generated X-RapidAPI-Proxy-Secret. 2) Using the hidden headers or parameters to integrate with your APIs existing authentication system.

X-RapidAPI-Proxy-Secret

API providers should use the X-RapidAPI-Proxy-Secret header described in the "Headers Sent by Mashape Proxy" section as well as whitelist the Mashape IPs indicated here to validate all requests coming from RapidAPI. This is a great way to quickly integrate with the RapidAPi system. All you will need to do is make sure that your API allows requests that contain the X-RapidAPI-Proxy-Secret header and let RapidAPI handle the rest. The Proxy Secret can be found under the APIs 'Settings' tab.

Hidden Header or Parameter Transformations

If your API already requires a certain type of authentication(i.e. you already have a parameter called api_key that is required), we recommend using a single access token to authenticate all RapidAPI users. Simply generate an API access token in your authentication service, then add the authentication headers or parameters in the "Transformations" section under the "Settings" for your API. The secret headers and parameters will be added in the background to every request that is made by a user subscribed to your API. The user will never see this hidden parameter you have defined.

API Endpoint Definition

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. To start, go to the 'Endpoints' tab of your API listing.

API Groups

If your API has endpoints that can be grouped together, then you will want to first use the 'Create Groups' functionality to define your API groups. Once a group is defined, it can be selected when you're creating a new API endpoint.

API Endpoints

The next step is going to be selecting 'Create 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.
  • Method: - Defines the HTTP method that will be used to call your endpoint. RapidAPI supports GET, POST, PUT, PATCH, and DELETE.
  • Group: - API groups are used to visualize similar API endpoints together, which allows developers to find similar endpoints faster.
  • Path: - The route to the endpoint, remember 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, therefore, you can use curly braces to encapsulate the user-defined parameter. For example, if I enter “/status/{appid}” as a Route an additional parameter input box will be created for the user to specify the parameter’s value in the console once you’ve saved the endpoint.

The next section will cover Step 3, which goes into defining the different types of headers and parameters that RapidAPI support.

Defining Headers and Parameters

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. Click the '+ Add Query Parameter' link to begin!

  • Name: - The name of the parameter.
  • Optional vs. Required: - A query string parameter can be optional or required, you are in control and decide whether you want to require the user to specify a value or not.
  • Type: - Sets the type of the value for the parameter. (Supported types: String, Number, Boolean, Enum, Date, Time, Geopoint).
  • Description: - Describe in a few words what the query parameter is all about.

Request Headers

Just like a query-string parameter, you can specify custom headers to be passed to your API endpoint by the user. Simply select the “+ Add Header Parameter” link.

  • Name: - The name of the header.
  • Optional vs. Required: - A header can be optional or required, you are in control and decide whether you want to require the user to specify a value or not.
  • Type: - Sets the type of the value for the header. (Supported types: String, Number, Boolean, Enum, Date, Time, Geopoint).
  • Description: - Describe in a few words what the header is.

Payloads (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.

Depending on the type of payload you would like to define, select the right option for you.

Below I'll detail the two types of payload definition.

Payload Form Encoded Parameters

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

  • Name: - The name of the form payload parameter.
  • Optional vs. Required: - A form parameter can be optional or required, you are in control and decide whether you want to require the user to specify a value or not.
  • Type: - Sets the type of the value for the header. (Supported types: String, Number, Boolean, Enum, Date, Time, Geopoint, and Binary(File upload)).
  • Default Value: - The value defined here will be displayed to users by default.
  • Description: - Describe in a few words what the header is.

Payload Models

By defining a payload to be posted to an endpoint in this way you have a lot of flexibility, as you can specify a lot of parameters.

  • Model Name: - The name you will assign to this model to identify it amongst the other ones
  • Format: - You can choose whether you will pass the payload to the endpoint in either JSON, XML, plain Text or BINARY.
  • Description: - Providing a description for your model so that you can inform the user on what he’s expected to pass
  • Sample Body: - This is an example of what the model looks like. For example, for a JSON model it might be:
{ 
	"name" : "RapidAPI",
	"text" : "This model always works"
}

Updated 7 days ago

Documenting Your API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.