specification extensions

APIs.guru Specification (vendor) extensions

The APIs.guru API collection defines and uses a number of OpenAPI specification extensions (known as vendor extensions in Swagger 2.0).

See also these vendors with their own extensions documented.

• Amazon AWS
• Microsoft Azure
• Rebilly Redoc

x-origin

A property of the info object, the x-origin structure is used to document the source and format of an API in the collection. It is used to round-trip the process of keeping the APIs updated.

Example structure

info:
  x-origin:
    format: swagger
    url: 'https://raw.githubusercontent.com/Mermade/bbcparse/master/iblApi/swagger.json'
    version: '2.0'

Please note, currently, if you include an x-origin extension within your API definition it will be removed. From April 2017, this extension will change to an array of the structure above. APIs.guru will then append to this array if it exists, allowing an audit trail of the source(s) of an API definition.

Valid values for format

• swagger
• api_blueprint
• raml
• google

In your own x-origin entries you may alternatively use a contentType property instead of a format property.

You may also specify the converter and version used.

{
  "url": "http://programmes.api.bbc.com/nitro/api",
  "contentType": "application/json",
  "converter": {
    "url": "https://github.com/mermade/bbcparse",
    "version": "1.2.0"
  }
}

x-providerName

A property of the info object, x-providerName is used to identify the domain of the API host. It is added automatically by APIs.guru

x-serviceName

A property of the info object, x-serviceName is used to distinguish APIs which are served from the same domain. It may be the subdomain if the API uses one. It is added automatically by APIs.guru

x-preferred

A property of the info object, x-preferred is a Boolean property which distinguishes between multiple versions of the same API. Where the x-providerName and x-serviceName are the same, only one definition should be marked x-preferred: true. This helps users of the APIs.guru collection organise and display the APIs.

x-hasEquivalentPaths

A property of the root object, x-hasEquivalentPaths indicates the source specification has multiple paths which map to the same OpenAPI path (possibly disambiguated with HTML fragment identifiers). Boolean

x-unofficialSpec

A property of the info object, x-unofficialSpec indicates the definition is produced by a third-party, either manually, by scraping existing documentation or converting a proprietary/undocumented format. Boolean

x-logo

A property of the info object, the x-logo structure holds a URL to the API logo and an optional background colour in HTML hex notation.

info:
  x-logo:
    backgroundColor: '#FFFFFF'
    url: 'http://static.bbci.co.uk/tviplayer/1.101.2/img/navigation/iplayer_pink.svg'

x-apiClientRegistration

A property of the info object, x-apiClientRegistration includes a URL-formatted property url containing the URL to the resource where developers can register to authenticate with the API.

"info": {
  "x-apiClientRegistration": {
    "url": "https://developer.bbc.co.uk/user/register"
  }
}

x-apisguru-categories

A property of the info object, x-apisguru-categories is an array of valid values from the list of APIs.guru categories.

x-tags

Also a property of the info object, x-tags is an array of free-form keywords/tags applicable to the API.