Documentation Get Support

Mashape Description Structure

A Mashape Description is made of three different sections:

These are defined inside a root <api> tag. Like:

<api xmlns="http://mashape.com"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://mashape.com http://mashape.com/schema/mashape-4.0.xsd">

	<!-- Authentication (if any) -->
	<authentication></authentication>

	<!-- List of endpoints -->
	<endpoint></endpoint>

	<!-- List of models (if any) -->
	<model></model>

</api>

Authentication → Go to definition

APIs can have an existing authentication in place, like Basic Authentication or Query Authentication (when the authentication credentials are submitted as parameters in the request).

An existing authentication can be described using the <authentication> tag:

<authentication type="Basic"></authentication>

Some authentications, like Basic Authentication, have a standard scheme so no additional information are required. For some others, like a Query Authentication, you might want to describe the required parameters, like:

<authentication type="query">
	<description><![CDATA[Please Signup or Login at http://service.com to get your Api Key]]></description>
		<authenticationparameters>
		<authenticationparameter name="apikey" optional="false">
			<description><![CDATA[This is your private Api Key]]></description>
		</authenticationparameter>
	</authenticationparameters>
</authentication>

The Mashape Description above tells that an apikey parameter should be appended to the request to authenticate the user. This will be handled by our client libraries, so you can avoid adding an "apiKey" parameter to each endpoint's route.


If your API has OAuth1.0a or OAuth2, you have to configure it (basically you have to list the URLs needed to authenticate). For OAuth1.0a:

	<authentication type="OAuth1.0a">
		<configuration name="authorizationUrl" value="https://api.domain.com/auth" />
		<configuration name="requestTokenUrl" value="https://api.domain.com/token" />
		<configuration name="accessTokenUrl" value="https://api.domain.com/access" />
	</authentication>

And for OAuth2:

	<authentication type="OAuth1.0a">
		<configuration name="authorizationUrl" value="https://api.domain.com/auth" />
		<configuration name="accessTokenUrl" value="https://api.domain.com/access" />
		<configuration name="scope" value="location" >
			<description>Read/write access to location info</description>
		</configuration>
				<configuration name="scope" value="user" >
			<description>Read/write access to profile info only </description>
		</configuration>
	</authentication>

Endpoints → Go to definition

An API should have at least one endpoint. Otherwise, it's useless. Endpoints usually have five main parts:

And may be optionally protected by an existing Authentication.

Consider the following JSON endpoint. This endpoint will be used as a reference in all following examples on this page.

GET
/users/123?hideEmails=true

JSON response:

{
    "username": "john12345",
    "role": "ADMIN",
    "address": {
        "street": "156 2nd Street",
        "zipcode": "94105",
        "city": "San Francisco",
        "state": "CA",
        "country": "US"
    },
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}

Its Mashape description is:

<api xmlns="http://mashape.com"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemalocation="http://mashape.com http://mashape.com/schema/mashape-4.0.xsd">
<endpoint http="GET" name="Get User" group="Users">
    <route><![CDATA[/users/{id}]]]></route>
    <parameters>
        <parameter name="id" type="Integer" />
        <parameter name="hideEmails" type="Boolean" optional="true" default="false" />
    </parameters>
    <response type="User" />
    <errors>
        <error code="404">
            <description><![CDATA[User not found]]></description>
        </error>
        <error code="401">
            <description><![CDATA[Please authenticate to consume this endpoint]]></description>
        </error>
    </errors>
</endpoint>
<model name="User">
	<example>
<![CDATA[
{
    "username": "john12345",
    "role": "ADMIN",
    "address": {
        "street": "156 2nd Street",
        "zipcode": "94105",
        "city": "San Francisco",
        "state": "CA",
        "country": "US"
    },
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}
]]>
	</example>
</model>
</api>

Endpoint attributes

As you can see, an <endpoint> describes an HTTP Method like GET , POST , PUT , or DELETE.

It also has a human-readable name and can be protected with an Authentication by setting the boolean attribute authentication.

An API can't have more that one Authentication.

Sometimes multiple endpoints belong to the same category of actions. For example endpoints like:

  • Get User
  • Delete User
  • Update User

All belong to the same "Users" group, which can be specified with the group attribute. Endpoints that belong to the same group will be grouped in the API documentation, like:

The image above could be the API Profile representation for the following draft description:

<endpoint http="GET" name="Get User" group="users">
	<!-- Endpoint description here -->
</endpoint>
<endpoint http="DELETE" name="Delete User" group="users">
	<!-- Endpoint description here -->
</endpoint>
<endpoint http="GET" name="Get Message" group="messages">
	<!-- Endpoint description here -->
</endpoint>
<endpoint http="DELETE" name="Delete Message" group="messages">
	<!-- Endpoint description here -->
</endpoint>
<endpoint http="PUT" name="Update Message" group="messages">
	<!-- Endpoint description here -->
</endpoint>

Route → Go to definition

The <route> element contains the route URL that targets the endpoint (without the base URL, which is set in the Proxy Settings). It can have dynamic parameters that are enclosed inside curly brace placeholders, like {parameter} . In the line from the previous example:

<route><![CDATA[/users/{id}]]></route>

the route contains a dynamic parameter id , and a regular parameter hideEmails .

Placeholder

Parameters in a route whose value can be set by the client must be enclosed in curly braces.
For example a route like <route><![CDATA[/users/{id}/comments/{commentId}]]></route> may accept requests like:

  • /users/1/comments/543
  • /users/12314341/comments/first
  • /users/john/comments/1

Parameters → Go to definition

Every parameter accepted by the endpoint must be listed inside the <parameters> collection with a <parameter> tag. Dynamic parameters marked with placeholders must be included as well.

They can have a type , be optional and/or have a default value, like:

<route><![CDATA[/users/{id}]]></route>
<parameters>
    <parameter name="id" type="Integer" />
    <parameter name="hideEmails" type="Boolean" optional="true" default="false" />
</parameters>

Available parameter types are: Number , Boolean , String .

Optionally, you can also add a <description> and a list of accepted <values> in case the parameter is an enumeration, like:

<parameters>
    <parameter name="id" type="Integer" />
    <parameter name="hideEmails" type="Boolean" optional="true"
	default="false">
		<description><![CDATA[Tell the API to return a list of emails belonging to the user]]></description>
		<values>
			<value>true</value>
			<value>false</value>
		</values>
	</parameter>
</parameters>

Constants → Go to definition

If you have to define some constant parameters, there is a dedicated XML element to simplify this:

<route><![CDATA[/endpoint]]></route>
<parameters>
    <constant name="method" type="getUsers" />
</parameters>

The result of this definition will be a request to /endpoint?method=getUsers


Response → Go to definition

Endpoints can have a response body described in a <response> tag. A response can return a plain String , Binary value (ie, for streaming APIs), or a Model. In the following example the response body is a model:

<response type="User" />

Every type name other than String or Binary is considered a Model . If the endpoint returns a model, a model description is expected to be found in a <model> tag, as you will learn below.

Sometimes an endpoint may return an array of Models. Arrays are described using the special keyword List[ModelName] , like:

<response type="List[User]" />

Remember that the keyword List[ModelName] can only be used with models. For example List[String] or List[Binary] is invalid.

If the <response> tag is omitted, it's assumed that the endpoint doesn't return any response body.

Errors → Go to definition

Endpoints can also return HTTP errors, which are described with an <error> tag inside an <errors> collection, like:

<errors>
	<error code="404">
	    <description><![CDATA[User not found]]></description>
	</error>
	<error code="401">
	    <description><![CDATA[Please authenticate to consume this endpoint]]></description>
	</error>
</errors>

As you might guess, code is the HTTP Status code returned by the error. Optionally errors can have a description .

Sometimes errors can have a response body, which is described with the type attribute, like:

<error code="500" type="String">
    <description><![CDATA[A server error occurred. More information in the body.]]></description>
</error>

The type attribute follows the same conventions of the Response tag, thus the response body can be String , Binary , or a custom Model. Errors could also return an array of models with the List[ModelName] syntax, like:

<error code="500" type="List[ErrorReason]">
    <description><![CDATA[A server error occurred. More information in the body.]]></description>
</error>

Every time a Model name is specified in a response, its description must be added within a model tag.

Models → Go to definition

Models are custom responses that can be returned by an Endpoint or an Error. They're described using the <model> tag.

Mashape fully supports JSON models. More formats and protocols will be supported like RESTful XML or SOAP. You can ask us to support them on Mashape Support.

Every time an Endpoint or an Error returns a model, it must be described with the <model> tag. Models can be described in two ways:

As with other elements, it's up to you to choose how verbose the description should be. The name attribute its mandatory.

Simple Description

A model can be described by simply putting its JSON representation into the <example> tag, like:

<model name="User">
	<example>
<![CDATA[
{
    "username": "john12345",
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}
]]>
	</example>
</model>

Sometimes this is enough to make developers understand what kind of response is returned.

Extended Description

The Simple Description can be optionally integrated with a specific description for every JSON field (in a 1:1 representation). For example the description above could be extended to:

<model name="User">
	<example>
<![CDATA[
{
    "username": "john12345",
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}
]]>
	</example>
	<fields>
		<simple name="username" optional="false" type="String">
			<description>This is the username</description>
			<example>tom971</example>
		</simple>
		<simple name="emails" optional="false" type="List[String]" />
	</fields>
</model>

As you can see the fields are individually described to provide a better documentation to developers.

You'll notice that the emails field has a List[String] type.

While it is not allowed to have a list of String in endpoint Responses and Errors, instead here in <simple> tags you can do it, because it represents a JSON array like: ["one", "two", "three"]

Two types of <fields> exist:

Simple Fields → Go to definition

Simple fields are used to represent any kind of value that is not a Model. Allowed types are String, Number and Boolean.

Complex Fields → Go to definition

If a field contains another Model, then it is a <complex> field. For example let's consider a more complex response with an embedded Address model, like:

{
    "username": "john12345",
    "role": "ADMIN",
    "address": {
        "street": "156 2nd Street",
        "zipcode": "94105",
        "city": "San Francisco",
        "state": "CA",
        "country": "US"
    },
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}

This can be extensively described as:

<model name="User">
	<fields>
		<simple name="username" optional="false" type="String">
			<description>This is the username</description>
			<example>tom971</example>
		</simple>
		<simple name="role" optional="false" type="String" default="USER" >
			<description>This is the username</description>
			<example>ADMIN</example>
			<values>
				<value>USER</value>
				<value>POWER_USER</value>
				<value>ADMIN</value>
			</values>
		</simple>
		<complex name="address" optional="false" type="Address">
			<description>This is an Address model</description>
		</complex>
		<simple name="emails" optional="false" type="List[String]" />
	</fields>
</model>
<model name="Address">
	<example>
<![CDATA[
{
	"street": "156 2nd Street",
	"zipcode": "94105",
	"city": "San Francisco",
	"state": "CA",
	"country": "US"
}
]]>
	</example>
</model>

Because the address field returns a Model named Address, an additional Address model must be also defined.