name

string

yes

The name of the API. This is not shown/displayed anywhere in the rendered page.

version

string

yes

The version of the API, e.g. "v1.0".

title

string

yes

The title of the API that is displayed in the API selection drop-down menu, e.g. "Daily Deals API".

description

string

yes

The description of the API. This is displayed directly under the API selection drop-down menu when the corresponding API is selected, e.g. "The Daily Deals API provides a real-time look into the current daily deals based on ZIP code and radius". This value supports Markdown syntax.

protocol

string

yes

The protocol described by this document, e.g. "rest".

basePath

string

yes

The base URL path for REST requests, including scheme name. Port number is optional. e.g. "https://api.acme.mashery.com:443"

auth

object

no

Links to key and/or OAuth objects.

auth.key

object

no

Links to param and secret objects.

auth.key.location

string

no

Location of API key. Default location is the  query string for GET requests, and encoded parameter request body for POST requests. Also determines location of signature key/value pair. To override default location, valid values are "query", "pathReplace", "body" and "header".  Additionally, you can supply one or more of the above values separated by a comma. (e.g. "query,header" would place the API key parameter in both the query string and as a request header value pair).

auth.key.param

string

no

Name of the API key parameter, e.g. "api_key" or "key". Defaults to "apiKey".

auth.key.secret

object

no

Links to the param and type objects.

auth.key.secret.param

string

no

Name of the API key secret parameter, e.g. "secret"

auth.key.secret.type

string

no

Type of secret signature method, e.g. "signed_md5" or "signed_sha256"

auth.basicAuth

boolean

no

Whether the basic authentication is required, either "true" or "false".

auth.oauth

object

no

OAuth version and flow definition.

auth.oauth.version

enum

string

no

OAuth version (e.g. “2.0”). "1.0a" and "2.0"

auth.oauth.base_uri

string

no

The base URI for the OAuth service endpoints. This value prepends the authorize_uri and access_token_uri values below, e.g. "http://yourdomain.com"  (optional)

auth.oauth.authorize_uri

string

no

The endpoint where the end-user is sent to authorize their account and grant permissions, e.g. "/oauth/authorize". If base_uri is not defined, a fully qualified URI is required.

auth.oauth.access_token_uri

string

no

The endpoint where the access token is granted, e.g. "/oauth/access_token". If base_uri is not defined, a fully qualified URI is required.

auth.oauth.access_token_location

enum type string

no

The location of the oauth access token. Possible values: "header" or "query"

auth.oauth.auth_flows

array

no

Array of strings, each string containing one of the four supported flows, e.g. "auth_code", "client_cred", "password_cred", or "implicit"

auth.oauth.options

object

no

Links to OAuth options objects, e.g. "authorize" (often used to hold authorize and scope details). (optional)

auth.soap

object

no

SOAP auth definition.

auth.soap.basic

boolean

no

Whether SOAP basic auth is enabled.

auth.soap.wss

object

no

SOAP WSS Security definition

auth.soap.wss.binary_security_token

boolean

no

Whether   SOAP WSS BinarySecurityToken auth is enabled.

auth.soap.wss.user_name_token

object

no

SOAP WSS UserNameToken auth definition.

auth.soap.wss.user_name_token.fields

array

no

Array of strings, each string is the name of an optional auth parameter field.

schemas

object

no

The schemas (body structure definitions) used by the web API.

schemas.(key)

object

no

An individual schema description. See JSON schema for more information.

schemas.(key).id

string

no

Unique identifier for this schema. Example: URL

schemas.(key).type

string

yes

The value type for this schema. A list of values can be found at the "type" section in the JSON Schema.

schemas.(key).$ref

string

no

A reference to another schema. The value of this property is the ID of another schema.

schemas.(key).description

string

no

A description of this object.

schemas.(key).default

string

no

The default value of this property (if one exists).

schemas.(key).required

boolean

no

Whether the parameter is required.

schemas.(key).format

string

no

An additional regular expression or key that helps constrain the value. For more details see the Type and Format Summary.

schemas.(key).pattern

string

no

The regular expression this parameter must conform to.

schemas.(key).minimum

string

no

The minimum value of this parameter.

schemas.(key).maximum

string

no

The maximum value of this parameter.

schemas.(key).enum[]

array

no

Values this parameter may take (if it is an enum).

schemas.(key).enumDescriptions[]

array

no

The descriptions for the enums. Each position maps to the corresponding value in theenum array.

schemas.(key).properties

object

no

If this is a schema for an object, list the schema for each property of this object.

schemas.(key).properties.(key)

object

no

A single property of this object. The value is itself a JSON Schema object describing this property.

schemas.(key).additionalProperties

object

no

If this is a schema for an object, this property is the schema for any additional properties with dynamic keys on this object.

schemas.(key).items

object

no

If this is a schema for an array, this property is the schema for each element in the array.

resources

object

yes

The resources in the API.

resources.(key)

object

yes

An individual resources description or name. Contains methods related to this resource.

resources.(key).methods

object

yes

Methods on this resource.

resources.(key).methods.(key)

object

yes

Description for any methods on this resource. The value at this level (string) contains name of this method.

resources.(key).methods.(key).path

string

yes

The URI path of this REST method. Should be used in conjunction with the basePath property at the API-level.

resources.(key).methods.(key).httpMethod

string

yes

HTTP method used by this method, e.g. "GET", “POST”, “PUT”, “DELETE”.

resources.(key).methods.(key).description

string

yes

Description of this method. This value supports Markdown syntax.

resources.(key).methods.(key).parameters

object

yes

Details for all parameters in this method.

resources.(key).methods.(key).parameters.(key)

object

yes

Details for a single parameter in this method (object). The value assigned at this level (string) would be the name of the parameter.

resources.(key).methods.(key).parameters.
(key).description

string

yes

A description of the parameter. This value supports Markdown syntax.

resources.(key).methods.(key).parameters.
(key).default

string

yes

The default value of this property (if one exists).

resources.(key).methods.(key).parameters.
(key).required

boolean

yes

Whether the parameter is required, either "true" or "false".

resources.(key).methods.(key).parameters.
(key).enum

array

no

Values this parameter may take.

resources.(key).methods.(key).parameters.
(key).enumDescriptions

array

no

The descriptions for the enums. Each position maps to the corresponding value in the "enum" array.

resources.(key).methods.(key).parameters.
(key).location

enum type string

yes

Whether this parameter goes in the query, path (for REST requests) or header.  Valid values are "query", "pathReplace", "body" and "header".

resources.(key).methods.(key).parameters.
 (key).type

string

no

The parameter type, which the I/O docs UI uses to provide an optimal form field editor. Valid values are: "boolean", "date", "double", "integer", "number", "string", and "textarea".

resources.(key).methods.(key).request

object

no

Schema for the request body.

resources.(key).methods.(key).request.$ref

string

no

Schema ID for the request schema. Value is a string key reference to a schema defined in schemas.(key).

resources.(key).methods.(key).response

object

no

Schema for the response body.

resources.(key).methods.(key).response.$ref

string

no

Schema ID for the response schema. Value is a string key reference to a schema defined in schemas.(key).