Documentation Get Support

XML Element Definitions

In the Structure documentation, we familiarize you with the Mashape Description elements. To better understand what each tag does, we suggest taking a look at the following definition table. You will discover a number of new tags that were deliberately omitted from the walkthrough for the sake of simplicity.

You can download the XML schema here or ping us at Mashape Support if you have questions or feedback.

Element Description

It's the root element that contains all the other XML elements. You can add an XML Schema to it, 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">
	<!-- Mashape Description here -->
</api>

Parent Element: None
Child Elements: <authentication> <endpoint> <model>


Describes an existing API authentication. This value is used in the API profile (for documenting how to get access to your API) and in the client libraries (they will automagically append headers or query parameter to authenticate with your service).

Attribute Description
type

Required

The type of the authentication implemented in your API.

Supported types, at this moment: Query Header Basic OAuth1.0a OAuth2

Parent Element: <api>
Child Elements: <description> <authenticationparameters> <configuration>


When the authentication is OAuth1.0a or OAuth2, configuration URLs must be described using this element for every URL.

Attribute Description
name

Required

The name of the required parameter, For OAuth1.0a they are authorizationUrl, requestTokenUrl and accessTokenUrl. While for OAuth2 they are: authorizationUrl, accessTokenUrl

and one or more scope parameters

value

Required

URL for the related configuration key (see names)

Parent Element: <authentication>
Child Elements: <description>


When the authentication is of Query or Header type, at least one <authenticationparameter> must be described inside this collection.

Parent Element: <authentication>
Child Elements: <authenticationparameter>


Describes a required authentication parameter that must be filled when consuming a protected endpoint.

Attribute Description
name

Required

The name of the required parameter, like username or apiKey.

Parent Element: <authenticationparameters>
Child Elements: <description>


Describes an API endpoint. At least one endpoint must exist.

Attribute Description
http

Required

The HTTP method for the endpoint.

Allowed Values: GET POST PUT DELETE


name

Required

An human readable name for the endpoint.


group

A arbitrary group name to which the endpoint belong. On the API documentation the endpoints will be then grouped together accordingly to this value.

Parent Element: <api>
Child Elements: <description> <route> <parameters> <response> <errors>


It is required for every endpoint. Contains the route to the parent endpoint, without the base URL (which is set in the Proxy Settings). And without query string, that will be created from parameters and constants

The route can contains dynamic parameters defined within placeholders, like:

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

Parent Element: <endpoint>
Child Elements: None


If the endpoint has parameters or dynamic URL parameters (placeholders) in the route, then those parameters must be defined within this collection.

Parent Element: <endpoint>
Child Elements: <parameter> <constant>


Describes a request parameter, or a route placeholder. Every parameter supported by the endpoint, or present in the route as a placeholder, must have a description.

If the parameter is an enumeration, an optional element <values> can be added as a child.

Attribute Description
name

Required

The name of the parameter, or of the placeholder (without curly braces).


optional

Describes if the parameter is optional or not. Placeholders parameters can't be optional.

Allowed Values: true false


type

Describes the parameter type. Parameter types can't be lists: List[..].

Allowed Values: String Number Boolean


default

If the parameter is optional it may have a default value defined in this attribute.


Parent Element: <parameters>
Child Elements: <description> <example> <values>


Describes a constant parameter.

Attribute Description
name

Required

The name of the constant.


value

Required

The value of the constant

Parent Element: <parameters>
Child Elements: <description>


If the endpoint returns a response body, this tag describes what kind of response it returns.

<response type="String" />

Attribute Description
type

Required

Describes the response body type. It can also represent an array of Models. If the type is model or an array of models, the model description must exist inside a <model> element.

Allowed Values: String Binary ModelName List[ModelName]

Parent Element: <endpoint>
Child Elements: None


If the endpoint may return an error, include the description of every error inside this collection.

Parent Element: <endpoint>
Child Elements: <error>


Represent an error that may be returned by an endpoint. Like:

<errors>
	<error code="404" type="String">
		<description><![CDATA[Not found]]></description>
	</error>
</errors>

Attribute Description
code

Required

A valid HTTP Status Code in the 4** and 5** range.


type

If the error returns a body, this is its type. It can also represent an array of Models. If the type is model or an array of models, the model description must exist inside a <model> element.

Allowed Values: String Binary ModelName List[ModelName]

Parent Element: <errors>
Child Elements: <description>


Describes a Model returned by an Endpoint or Error. Only JSON data is supported in this version. At least an <example> or <fields> child must exist.

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

If the <example> element is missing, but a <fields> element is described, the <example> element is auto-generated by Mashape.

Attribute Description
name

Required

An unique model name.

Parent Element: <api>
Child Elements: <description> <example> <fields>


Contains a collection of <simple> or <complex> fields that accurately describe each field (in a 1:1 representation) of a <model> JSON representation.

<complex> elements are used to describe nested models (which basically are other JSON objects), while <simple> elements are used to describe plain String, Number or Boolean values.

Parent Element: <model>
Child Elements: <simple> <complex>


Describes a simple JSON field. For an example see Extended Model Description.

Attribute Description
name

Required

The name of the JSON field.


optional

Describes if the field is optional or not.

Allowed Values: true false


type

Describes the simple field type. It can't be a model. Field types can be lists of simple values: List[..].

Allowed Values: String Number Boolean List[String|Number|Boolean]


default

If the field is optional it may have a default value defined in this attribute.

Parent Element: <fields>
Child Elements: <description> <example> <values>


Describes a nested JSON object. For an example see Extended Model Description.

Attribute Description
name

Required

The name of the JSON field.


optional

Describes if the field is optional or not.

Allowed Values: true false


type

Describes the field type. It can only be a model. It can also be a lists of models: List[ModelName].

Allowed Values: ModelName List[ModelName]

Parent Element: <fields>
Child Elements: <description>


Contains an example value. Better if the value it's enclosed in a CDATA block.

<example><![CDATA[A sample value]]></example>

If the parent element is <model>, it contains an arbitrary JSON representation of a model, like:

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

Parent Element: <parameter> <model> <simple>
Child Elements: None


Enumerations can be described within this collection. For example:

<values>
	<value>RED</value>
	<value>WHITE</value>
	<value>BLACK</value>
</values>

Parent Element: <parameter> <simple>
Child Elements: <value>


Contains the value of an enumeration entry. For example:

<value>RED</value>

Parent Element: <values>
Child Elements: None


Contains an arbitrary description. Better if the value it's enclosed in a CDATA block. For example:

<description><![CDATA[This is a description]]></description>

Parent Element: <api> <authentication> <authenticationparameter> <endpoint> <parameter>
Child Elements: None