Documentation Get Support

Describing an API with XML

Describing an API is required to have a nice documentation layout and auto-generate client libraries. Also, without a description the API Profile would look empty and meaningless. The description is written into an XML file that is then uploaded to Mashape, and basically consists of describing what the API does: its authentication scheme, endpoints and models.

Luckily, the process just takes a few minutes for mid-size APIs.

If you wonder why we have chosen XML, it's because it's a lot easier to describe things when an XML schema is provided. As you might guess, we have created an XML Schema that you can download here.

A sample Mashape Description is also available here.

We fully support descriptions for RESTful JSON APIs. More formats and protocols will be supported, like RESTful XML and SOAP. If there's a format/protocol you would like to see on Mashape, you can ping us at Mashape Support.

Below is a step by step guide that explains how to write a Mashape Documentation for a RESTful JSON API. This guide introduces the basic elements needed to describe an API, but should not be seen as an exhaustive showcase of every tag. To see an in-depth description of each XML element, we have an XML Element Definitions analytical table that illustrates every XML element and its attributes.

How does it look like?

Suppose we have the following endpoint (on the left). A Mashape Description for it could be (on the right):

JSON Endpoint
GET  
/users/{id}

JSON response:

{
    "username": "john12345",
    "emails": [
        "email1@john12345.com",
        "email2@john12345.com"
    ]
}
Mashape Description
<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">
        <route><![CDATA[/users/{id}]]></route>           
        <parameters>
            <parameter name="id" type="Integer" />
        </parameters>
        <response type="User" />
    </endpoint>

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

This is a minimal example. The Mashape Description allows you to be much more expressive, as you will learn below. It's up to you to decide how much information you want to show to make the API understandable by third-party developers.

For example, if we had chosen to be more verbose, the endpoint above could have been described 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">
    <endpoint http="GET" name="Get User">
        <route><![CDATA[/users/{id}]]></route>            
        <parameters>
            <parameter name="id" type="Integer" optional="false">
				<description><![CDATA[This is an existing User ID]]></description>
			</parameter>
        </parameters>
        <response type="User" />
		<errors>
			<error code="404">
				<description><![CDATA[User not found]]></description>
			</error>
		</errors>
    </endpoint>
 
    <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>
</api>