Documenting an API

The most important part of listing your API on Mashape is making sure developers can run it from the comfort of their browser; in doing so, you enable them to quickly abstract what endpoints to query and see the resulting queries displayed with only a few clicks. Exhaustively documenting an API is crucial. A well documented, simple to use API is a good API!


Table of Contents

  1. API Authentication
  2. API Endpoint definition
  3. API Querystring Parameter definition
  4. API Request Headers definition
  5. Defining Payloads Models
  6. Endpoint Payload as a Form Encoded model definition
  7. Endpoint Payload as a Model definition

API Authentication

The most important part of releasing your public API is making it easy for developers to consume. Make your API standout with easy to understand documentation and endpoint descriptions.

Nearly all APIs require a form of authentication. From the Documentation view you’ll define how users will authenticate with your API. Let’s hit the button:

Defining Authentication Settings
Fig. 1 Defining Authentication Settings

A modal pops out asking us which of the following authentication methods the API we’re defining uses:

API Endpoint Definition

Clearly an API with no endpoints is not very useful, so let’s define some endpoints. We’re about to jump into hyperspace!

Defining Authentication Settings
Fig. 2 Adding an Endpoint made simple

The following modal pops up:

Defining Endpoints
Fig. 2.5 Defining Endpoints

Fields

  • Method: - Defines the way you will reach the endpoint, whether you’re Creating, Reading, Updating or Deleting you can pick a method from the available ones (as a refresh you can check out this article here). Mashape supports GET, POST, PUT, PATCH, DELETE methods
  • Route: - The route to the endpoint (remember your Base URL looks like https://api.domain.com/v3). The route builds from the Base URL so don’t forget to add an initial “/”, for example “/status”. 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. (See final result image)
  • Name: - You can provide a descriptive name for the endpoint or just set the name to match the route. This will be the name visualised in the quick menu on the right hand side of the Documentation explorer
  • Description: - This is kind of self-explanatory but important, it helps users understand what this endpoint does, make sure it is understandable

Defining Querystring Parameters

Adding a Query String parameter can be used to add additional parameters to a specific request. For example a filter (imagine “?limit” or “?offset”) could be an additional query string parameter passed with the request. Click the blue button to begin!

Adding parameters being passed with the query
Fig. 3 Adding parameters being passed with the query

Fields

  • Condition: - A query string parameter can be optional, constant or required, you are in control and decide whether you want the user to specify variable or not
  • Name: - The name given to the parameter, in “param=text” this value sets “param”.
  • Type: - Sets the type of the value for the parameter, a number, a string, boolean(true/false) or binary. If you specify a special character we convert it to its URLencoded version, for example “ü” becomes “%C3%BC”
  • Value: - When you set the Condition to “constant” you can enforce the value of the query parameters here, otherwise this is where you put its default value
  • Description: - Describe in a few words what the query parameter is all about!

Defining Querystring Parameters passed with the query
Fig. 3.5 Defining Querystring Parameters passed with the query

Request Headers:

Just like a querystring parameter you can specify custom headers to be passed to your API endpoint. Simply press the “Add header” button to pop up the dialog with the options.

Defining Headers being passed with the query
Fig. 4 Defining Headers being passed with the query

The below appears, and just like in the query parameter dialogue you can set the values for your header’s Condition, Name, Type, Value and Description.

Defining Header Properties
Fig. 5 Defining Header Properties

  • Condition: - A query string parameter can be optional, constant or required, you are in control and decide whether you want the user to specify variable or not
  • Name - The name given to the parameter, in “param=text” this value sets “param”.
  • Type - Sets the type of the value for the parameter, a number, a string, boolean(true/false) or binary. If you specify a special character we convert it to its URLencoded version, for example “ü” becomes “%C3%BC”
  • Value: - When you set the Condition to “constant” you can enforce the value of the query parameters here, otherwise this is where you put its default value
  • Description: - Describe in a few words what the query parameter is all about!

Defining a Payload (Only for POST, PUT and PATCH):

When you specify the method to query the endpoint as a POST, PUT or PATCH method you should also define a payload. You can add it as a single form value or as a model. You can add as many values as you require.

Two options are now available from the dialog:

Defining Header Properties
Fig. 6.1 Defining Header Properties

Defining a payload as a form encoded parameter

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

Defining Header Properties
Fig. 6.2 Defining Header Properties

Fields

  • Condition: - Can be optional, constant or required
  • Name: - The name given to the parameter, specified before its value. If you want to pass “color = red”, this refer to color.
  • Type: - Sets the type of the value for the parameter
  • Value: - When you set the Condition to “constant” you can enforce the value of the parameter, otherwise this is where you put its default value that a user can change.
  • Description: - Describe in a few words what this parameter is all about

Defining a payload as a model:

Defining Custom Payload as Model
Fig. 6.3 Defining Custom Payload as Model

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.

Fields

  • 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, BINARY or plain TEXT
  • Description: - Providing a description for your model so that you can inform the user on what he’s expected to pass
  • Sample Body: - Depends on the format, for example if it was JSON: { "sample":"never fails" }