Documenting an API


API Authentication

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

Using Rakuten 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.

alt text

Authentication Flow

Since Rakuten 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 API Proxy section as well as whitelist the our IPs indicated here to validate all requests coming from Rakuten RapidAPI. This is a great way to quickly integrate with the Rakuten 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 Rakuten RapidAPI handle the rest. The Proxy Secret can be found under the APIs ‘Settings’ tab.

alt text

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 Rakuten 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.

alt text

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’

alt text

The following page will then appear:

alt text

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. Rakuten 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 Rakuten 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!

alt text

  • 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.

alt text

  • 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.

alt text

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

alt text

  • 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

alt text

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:
JSON
{ 
	"name" : "Rakuten RapidAPI",
	"text" : "This model always works"
}