Distribute a JSON API

Overview

Distributing an API into the Mashape marketplace is easy if you already have an API that returns JSON data. Once published, you can also add our add-ons on top of your API for advanced features like the "Billing" or the "API request limit".

The requirements are:

• The API must return JSON data.
• The API that must have any sort of existing authentication disabled, like OAuth (we plan to add support for existing authentications in the next releases).

There are three steps:

• Create an XML file that describes the API and its methods, so we know what your API does.
• Configure the proxy on the wizard on mashape.com
• Go to the Wizard and fill in the required info.

When you're done, your API is ready to be published into the marketplace and hacked by thousands of hard-code developers :) We'll auto-generate client libraries for it, create a nice documentation, and give you custom URLs for sign up and login. Also you'll be able to add any of our add-ons on top of it.

Creating the XML description

The first step for distributing an API is to create an XML file that describes what the API does.

A sample XML description may be:

Below a quick summary (go to XML Elements for the full documentation)

• The root element is <api>.
• The root element may have a list of <method> and <object> elements.
• The <method> element has a name attribute, that is a human readable name of the action, and a http attribute, that is the HTTP Method required for the request (GET/POST/PUT/DELETE allowed).
• The <method> element has a child <url> element that is its URL without the baseUrl part. If the URL has parameters, they must be marked with a placeholder (an arbitrary name between curly braces)
• The <method> may have a list of <parameter> elements in the parent <parameters> collection: one for each placholder in the URL.
• The <parameter> element contains the name of the placeholder that is referring to (without curly braces), and may have an optional attribute if the parameter is not mandatory. Every parameter defined in the method's URL must have a parameter element associated.
• The <method> element may have a <result> child element if it returns a response. The response is a JSON object described in an <object> element.
• The <result> element has an object attribute, that is the name of an <object> element it refers to, and an array attribute if the result is an array of objects.
• The <method> element may also have an <error> child element if it may return an error response that is different from the <result> one.
• The <error> element has an object attribute, that is the name of an <object> element it refers to, and an array attribute if the result is an array of error objects.
• The <object> element has a name attribute, that is an arbitrary name for the object, and contains a list of <field>
• The <object> element has a name attribute, that is an arbitrary name for the object, and a list of <field> elements mapping the keys in the JSON response.
• The <field> element contains the name of the key in the JSON response that is mapping, and has an array attribute if it's an array of values, an optional attribute if it's optional and an object attribute with the name of an <object> element if it returns an object and not a simple value.

XML Schema

You can use a XML Schema while creating the XML file.

If you use the schema, remember to configure it properly in the root api element, like:

Methods

An API, like yours, can have many methods:

GET http://www.myapi.com/users/1

or

POST http://www.myapi.com/users?name=Sample+user&nickname=mashaper

The methods to distribute must be described using the <method> element. Continue reading for an example.

Parameters

Methods can have parameters. Any parameter whose value can change and be set by the client must be marked with a placeholder. The placeholder consists of an arbitrary name between curly braces and identifies a parameter .

For example considering GET http://www.myapi.com/users/1 , there's one route parameter that is the id of the user (here valued with 1 ).
To indicate that part of the route is a parameter, we can write:

GET http://www.myapi.com/users/{id}

Or for example considering POST http://www.myapi.com/users?username=A-VALUE&email=A-VALUE , we can write:

POST http://www.myapi.com/users?username={username}&email={email}

Because we want the client to be able to set username and email values when making a request to that endpoint.

So, every method is described by a <method> element. The <method> element has a name attribute that is an human readable text describing what it does, an http attribute defining the HTTP Method to use when calling it, and it has an <url> child element containing the route to the method without a base URL part (which is the Forward Address Proxy property set in the Wizard when you add a new API).

Considering the examples above, we can start writing the following XML code:

It's better to enclose the <url> value in a CDATA block because some URLs may contain special characters (like the ampersand char: & ).

Results

Methods may return a response, in this case the returned JSON response must be mapped in an <object> element, and then its name must be specified in a child <result> element inside the <method> .

For example, let's suppose that the method GET http://www.myapi.com/users/1 returns the following JSON data:

We're going to describe this result in an <object> element:

The <field> element is used to map the keys in the JSON response.

Then, after describing an <object> and its fields, we can set it as a result to a method, using the <result> element and its object attribute:

The same <object> can be used as the result of many methods.
Also more complex <object> can be described. For example considering the following JSON value:

It can be described like:

You can use the XML Result Generator tool to auto-generate the XML code for a given JSON value.

Errors

An error is simply an <object> that can be returned by a method instead of its <result> object.

Take a look at the following description:

The XML code above describes a method that could return a result like:

Or return an error like:

XML Elements

When creating the XML description, use the elements below:

XML Element	Description
api	It's the root element that contains all the other XML elements. Parent element: No parent element Child elements: method - object Attributes: No attributes
method	Describes an API method. At least one method should exist. Parent element: api Child elements: url - parameters - result - error Attributes: name [required] An human readable name describing the action done by the method. http [required] The accepted HTTP Method for an incoming request. Available values: GET - POST - PUT - DELETE
url	Describes the URL for a method, without the base URL part already set in the baseUrl attribute in the <api> element. The URL must begin with a slash / and end without the slash. Mutable parameters must be embraced between { and } . It's better to include the URL in a CDATA block. Parent element: method Child elements: No childs Attributes: No Attributes Examples: <![CDATA[/users]] <![CDATA[/users/{id}]] <![CDATA[/{param}/comments?anotherParam=value]] <![CDATA[/entity/{param}/entity2/{param2}?param3={param3}&anotherParam=value]]
parameters	It's the container element for a list of parameters of the method. Parameters marked with a placeholder must be defined here. Parent element: method Child elements: parameter Attributes: No Attributes
parameter	If the method has mutable parameters that can be set by the client, they must be described using this element, that is valued with the name of the parameter. Every placeholder defined in the URL of a method must be mapped with a <parameter> element, and the parameter's name is the placeholder's name without curly braces. Parent element: parameters Child elements: No childs Attributes: optional [optional] If the parameter is optional and it's not required to be valued by the client, then use this attribute. Available values: true - false Default value: false
result	If the method has a response, then use this element to define which <object> it returns. Parent element: method Child elements: No childs Attributes: name [required] The name of the <object> element it refers to. array [optional] A boolean value indicating if the method returns an array of objects. Available values: true - false Default value: false
error	If the method may return an error, then use this element to define which error <object> it returns. Parent element: method Child elements: No childs Attributes: name [required] The name of the <object> element it refers to. array [optional] A boolean value indicating if the method returns an array of objects. Available values: true - false Default value: false
object	It's a mapping to a JSON response. It describes the structure and the keys of a JSON response. Parent element: api Child elements: field Attributes: name [required] An arbitrary name for the object, to be used for references in <result> and <error> elements.
field	It describes a key in the JSON response. At least one field must exist in an object. This element contains the name of the field, and by default the name of the field is mapped to a key with the same name in the JSON response. Parent element: object Child elements: No childs Parameters: object [optional] If the field is another object, this is the name of the object it refers to. array [optional] A boolean value indicating if the field returns an array of values, or of objects if the object attribute is set. Available values: true - false Default value: false optional [optional] A boolean value indicating if the field is optional or not. Available values: true - false Default value: false

Configuring the proxy

Before publishing your API you must configure the proxy using the Wizard. This is required to connect your service to our platform and authorize the users that make requests to your API. It's a painless process. And because the proxy is open source, we can help you to install it on you infrastructure (contact support@mashape.com).

The proxy requires two fields:

• CNAME Alias: When you add a new API on Mashape we auto-generate a proxy DNS like 12345.proxy.mashape.com - if you want, you can set in this field a CNAME Alias that points to our proxy DNS, like api.myservice.com - Note: You can set a CNAME Alias only if the Forward Address is not an https endpoint.
• Forward Address: This is the base URL to your API methods, it's where the request will be forwarded by the proxy. For example http://myservice.com/api/v2