Discovery Document

The Discovery Document describes the surface for a particular version of an API. The information provided by the discovery document includes API-level properties such as an API description, resource schemas, authentication scopes, and methods.

Methods

The Discovery document focuses on the RESTful method of invoking an API. The discovery.apis.getRest method retrieves the REST-based Discovery document for a particular API.

getRest: Retrieve the description of a particular version of an API.
list: Retrieve the list of APIs supported at this endpoint.

Resource Representations

{
  "kind": "discovery#restDescription",
  "discoveryVersion": "v1",
  "id": string,
  "name": string,
  "version": string,
  "revision": string,
  "title": string,
  "description": string,
  "icons": {
    "x16": string,
    "x32": string
  },
  "documentationLink": string,
  "labels": [
    string
  ],
  "protocol": "rest",
  "baseUrl": string,
  "basePath": string,
  "rootUrl": string,
  "servicePath": string,
  "batchPath": "batch",
  "parameters": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "auth": {
    "oauth2": {
      "scopes": {
        (key): {
          "description": string
        }
      }
    }
  },
  "features": [
    string
  ],
  "schemas": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "methods": {
    (key): {
      "id": string,
      "path": string,
      "httpMethod": string,
      "description": string,
      "parameters": {
        (key): {
          "id": string,
          "type": string,
          "$ref": string,
          "description": string,
          "default": string,
          "required": boolean,
          "format": string,
          "pattern": string,
          "minimum": string,
          "maximum": string,
          "enum": [
            string
          ],
          "enumDescriptions": [
            string
          ],
          "repeated": boolean,
          "location": string,
          "properties": {
            (key): (JsonSchema)
          },
          "additionalProperties": (JsonSchema),
          "items": (JsonSchema),
          "annotations": {
            "required": [
              string
            ]
          }
        }
      },
      "parameterOrder": [
        string
      ],
      "request": {
        "$ref": string
      },
      "response": {
        "$ref": string
      },
      "scopes": [
        (value)
      ],
      "supportsMediaDownload": boolean,
      "supportsMediaUpload": boolean,
      "mediaUpload": {
        "accept": [
          string
        ],
        "maxSize": string,
        "protocols": {
          "simple": {
            "multipart": true,
            "path": string
          },
          "resumable": {
            "multipart": true,
            "path": string
          }
        }
      },
      "supportsSubscription": boolean
    }
  },
  "resources": {
    (key): {
      "methods": {
        (key): {
          "id": string,
          "path": string,
          "httpMethod": string,
          "description": string,
          "parameters": {
            (key): {
              "id": string,
              "type": string,
              "$ref": string,
              "description": string,
              "default": string,
              "required": boolean,
              "format": string,
              "pattern": string,
              "minimum": string,
              "maximum": string,
              "enum": [
                string
              ],
              "enumDescriptions": [
                string
              ],
              "repeated": boolean,
              "location": string,
              "properties": {
                (key): (JsonSchema)
              },
              "additionalProperties": (JsonSchema),
              "items": (JsonSchema),
              "annotations": {
                "required": [
                  string
                ]
              }
            }
          },
          "parameterOrder": [
            string
          ],
          "request": {
            "$ref": string
          },
          "response": {
            "$ref": string
          },
          "scopes": [
            (value)
          ],
          "supportsMediaDownload": boolean,
          "supportsMediaUpload": boolean,
          "mediaUpload": {
            "accept": [
              string
            ],
            "maxSize": string,
            "protocols": {
              "simple": {
                "multipart": true,
                "path": string
              },
              "resumable": {
                "multipart": true,
                "path": string
              }
            }
          },
          "supportsSubscription": boolean
        }
      },
      "resources": {
        (key): (RestResource)
      }
    }
  }
}

Property Name	Value	Description
`kind`	`string`	The kind for this response. The fixed string `discovery#restDescription`.
`discoveryVersion`	`string`	Indicate the version of the Discovery API used to generate this doc.
`id`	`string`	The ID of the Discovery document for the API. For example, `urlshortener:v1`.
`name`	`string`	The name of the API. For example, `urlshortener`.
`version`	`string`	The version of the API. For example, `v1`.
`revision`	`string`	The revision of the API.
`title`	`string`	The title of the API. For example, "Google Url Shortener API".
`description`	`string`	The description of this API.
`icons`	`object`	Links to 16x16 and 32x32 icons representing the API.
`icons.x16`	`string`	The URL of the 16x16 icon.
`icons.x32`	`string`	The URL of the 32x32 icon.
`documentationLink`	`string`	A link to human-readable documentation for the API.
`labels[]`	`list`	Labels for the status of this API. Valid values include `limited_availability` or `deprecated`.
`protocol`	`string`	The protocol described by the document. For example, REST.
`rootUrl`	`string`	The root url under which all API services live.
`parameters`	`object`	Common parameters that apply across all apis.
`parameters.(key)`	`nested object`	Description of a single parameter.
`parameters.(key).id`	`string`	Unique identifier for this schema.
`parameters.(key).type`	`string`	The value type for this schema. A list of values can be found at the "type" section in the JSON Schema.
`parameters.(key).$ref`	`string`	A reference to another schema. The value of this property is the ID of another schema.
`parameters.(key).description`	`string`	A description of this object.
`parameters.(key).default`	`string`	The default value of this property (if one exists).
`parameters.(key).required`	`boolean`	Whether the parameter is required.
`parameters.(key).format`	`string`	An additional regular expression or key that helps constrain the value. For more details see the Type and Format Summary.
`parameters.(key).pattern`	`string`	The regular expression this parameter must conform to.
`parameters.(key).minimum`	`string`	The minimum value of this parameter.
`parameters.(key).maximum`	`string`	The maximum value of this parameter.
`parameters.(key).enum[]`	`list`	Values this parameter may take (if it is an enum).
`parameters.(key).enumDescriptions[]`	`list`	The descriptions for the enums. Each position maps to the corresponding value in the enum array.
`parameters.(key).repeated`	`boolean`	Whether this parameter may appear multiple times.
`parameters.(key).location`	`string`	Whether this parameter goes in the query or the path for REST requests.
`parameters.(key).properties`	`object`	If this is a schema for an object, list the schema for each property of this object.
`parameters.(key).properties.(key)`	`nested object`	A single property of this object. The value is itself a JSON Schema object describing this property.
`parameters.(key).additionalProperties`	`nested object`	If this is a schema for an object, this property is the schema for any additional properties with dynamic keys on this object.
`parameters.(key).items`	`nested object`	If this is a schema for an array, this property is the schema for each element in the array.
`parameters.(key).annotations`	`object`	Additional information about this property.
`parameters.(key).annotations.required[]`	`list`	A list of methods that require this property on requests.
`auth`	`object`	Authentication information.
`auth.oauth2`	`object`	OAuth 2.0 authentication information.
`auth.oauth2.scopes`	`object`	Available OAuth 2.0 scopes.
`auth.oauth2.scopes.(key)`	`object`	The scope value.
`auth.oauth2.scopes.(key).description`	`string`	Description of scope.
`features[]`	`list`	A list of supported features for this API.
`schemas`	`object`	The schemas for this API.
`schemas.(key)`	`nested object`	An individual schema description.
`schemas.(key).id`	`string`	Unique identifier for this schema. Example: `URL`
`schemas.(key).type`	`string`	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`	A reference to another schema. The value of this property is the ID of another schema.
`schemas.(key).description`	`string`	A description of this object.
`schemas.(key).default`	`string`	The default value of this property (if one exists).
`schemas.(key).required`	`boolean`	Whether the parameter is required.
`schemas.(key).format`	`string`	An additional regular expression or key that helps constrain the value. For more details see the Type and Format Summary.
`schemas.(key).pattern`	`string`	The regular expression this parameter must conform to.
`schemas.(key).minimum`	`string`	The minimum value of this parameter.
`schemas.(key).maximum`	`string`	The maximum value of this parameter.
`schemas.(key).enum[]`	`list`	Values this parameter may take (if it is an enum).
`schemas.(key).enumDescriptions[]`	`list`	The descriptions for the enums. Each position maps to the corresponding value in the `enum` array.
`schemas.(key).repeated`	`boolean`	Whether this parameter may appear multiple times.
`schemas.(key).location`	`string`	Whether this parameter goes in the query or the path for REST requests.
`schemas.(key).properties`	`object`	If this is a schema for an object, list the schema for each property of this object.
`schemas.(key).properties.(key)`	`nested object`	A single property of this object. The value is itself a JSON Schema object describing this property.
`schemas.(key).additionalProperties`	`nested object`	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`	`nested object`	If this is a schema for an array, this property is the schema for each element in the array.
`schemas.(key).annotations`	`object`	Additional information about this property.
`schemas.(key).annotations.required[]`	`list`	A list of methods that require this property on requests.
`methods`	`object`	API-level methods for this API.
`methods.(key)`	`nested object`	An individual method description.
`methods.(key).id`	`string`	A unique ID for this method. This property can be used to match methods between different versions of Discovery.
`methods.(key).description`	`string`	Description of this method.
`methods.(key).parameters`	`object`	Details for all parameters in this method.
`methods.(key).parameters.(key)`	`nested object`	Details for a single parameter in this method.
`methods.(key).parameters.(key).id`	`string`	Unique identifier for this schema.
`methods.(key).parameters.(key).type`	`string`	The value type for this schema. A list of values can be found at the "type" section in the JSON Schema.
`methods.(key).parameters.(key).$ref`	`string`	A reference to another schema. The value of this property is the ID of another schema.
`methods.(key).parameters.(key).description`	`string`	A description of this object.
`methods.(key).parameters.(key).default`	`string`	The default value of this property (if one exists).
`methods.(key).parameters.(key).required`	`boolean`	Whether the parameter is required.
`methods.(key).parameters.(key).format`	`string`	An additional regular expression or key that helps constrain the value. For more details see the Type and Format Summary.
`methods.(key).parameters.(key).pattern`	`string`	The regular expression this parameter must conform to.
`methods.(key).parameters.(key).minimum`	`string`	The minimum value of this parameter.
`methods.(key).parameters.(key).maximum`	`string`	The maximum value of this parameter.
`methods.(key).parameters.(key).enum[]`	`list`	Values this parameter may take (if it is an enum).
`methods.(key).parameters.(key).enumDescriptions[]`	`list`	The descriptions for the enums. Each position maps to the corresponding value in the `enum` array.
`methods.(key).parameters.(key).repeated`	`boolean`	Whether this parameter may appear multiple times.
`methods.(key).parameters.(key).location`	`string`	Whether this parameter goes in the query or the path for REST requests.
`methods.(key).parameters.(key).properties`	`object`	If this is a schema for an object, list the schema for each property of this object.
`methods.(key).parameters.(key).properties.(key)`	`nested object`	A single property of this object. The value is itself a JSON Schema object describing this property.
`methods.(key).parameters.(key).additionalProperties`	`nested object`	If this is a schema for an object, this property is the schema for any additional properties with dynamic keys on this object.
`methods.(key).parameters.(key).items`	`nested object`	If this is a schema for an array, this property is the schema for each element in the array.
`methods.(key).parameters.(key).annotations`	`object`	Additional information about this property.
`methods.(key).parameters.(key).annotations.required[]`	`list`	A list of methods for which this property is required on requests.
`methods.(key).parameterOrder[]`	`list`	Ordered list of required parameters. This serves as a hint to clients on how to structure their method signatures. The array is ordered such that the most significant parameter appears first.
`methods.(key).scopes[]`	`list`	OAuth 2.0 scopes applicable to this method.
`methods.(key).supportsMediaDownload`	`boolean`	Whether this method supports media downloads.
`methods.(key).supportsMediaUpload`	`boolean`	Whether this method supports media uploads.
`methods.(key).mediaUpload`	`object`	Media upload parameters.
`methods.(key).mediaUpload.accept[]`	`list`	MIME Media Ranges for acceptable media uploads to this method.
`methods.(key).mediaUpload.maxSize`	`string`	Maximum size of a media upload, such as "1MB", "2GB" or "3TB".
`methods.(key).supportsSubscription`	`boolean`	Whether this method supports subscriptions.
`baseUrl`	`string`	[DEPRECATED] The base URL for REST requests.
`basePath`	`string`	[DEPRECATED] The base path for REST requests.
`servicePath`	`string`	The base path for all REST requests.
`batchPath`	`string`	The path for REST batch requests.
`methods.(key).path`	`string`	The URI path of this REST method. Should be used in conjunction with the `servicePath` property at the API-level.
`methods.(key).httpMethod`	`string`	HTTP method used by this method.
`methods.(key).request`	`object`	The schema for the request.
`methods.(key).request.$ref`	`string`	Schema ID for the request schema.
`methods.(key).request.parameterName`	`string`	[DEPRECATED] Some APIs have this field for backward-compatibility reasons. It can be safely ignored.
`methods.(key).response`	`object`	The schema for the response.
`methods.(key).response.$ref`	`string`	Schema ID for the response schema.
`methods.(key).mediaUpload.protocols`	`object`	Supported upload protocols.
`methods.(key).mediaUpload.protocols.simple`	`object`	Supports uploading as a single HTTP request.
`methods.(key).mediaUpload.protocols.simple.multipart`	`boolean`	True if this endpoint supports upload multipart media.
`methods.(key).mediaUpload.protocols.simple.path`	`string`	The URI path to be used for upload. Should be used in conjunction with the `rootURL` property at the api-level.
`methods.(key).mediaUpload.protocols.resumable`	`object`	Supports the Resumable Media Upload protocol.
`methods.(key).mediaUpload.protocols.resumable.multipart`	`boolean`	`true` if this endpoint supports uploading multipart media.
`methods.(key).mediaUpload.protocols.resumable.path`	`string`	The URI path to be used for upload. Should be used in conjunction with the `rootURL` property at the API-level.
`resources`	`object`	The resources in this API.
`resources.(key)`	`nested object`	An individual resource description. Contains methods and sub-resources related to this resource.
`resources.(key).methods`	`object`	Methods on this resource.
`resources.(key).methods.(key)`	`nested object`	Description for any methods on this resource.
`resources.(key).methods.(key).id`	`string`	A unique ID for this method. This property can be used to match methods between different versions of Discovery.
`resources.(key).methods.(key).path`	`string`	The URI path of this REST method. Should be used in conjunction with the `servicePath` property at the API-level.
`resources.(key).methods.(key).flatPath`	`string`	The URI path of this REST method in (RFC 6570) format without level 2 features ({+var}). Supplementary to the `path` property.
`resources.(key).methods.(key).httpMethod`	`string`	HTTP method used by this method.
`resources.(key).methods.(key).description`	`string`	Description of this method.
`resources.(key).methods.(key).parameters`	`object`	Details for all parameters in this method.
`resources.(key).methods.(key).parameters.(key)`	`nested object`	Details for a single parameter in this method.
`resources.(key).methods.(key).parameters.(key).id`	`string`	Unique identifier for this schema.
`resources.(key).methods.(key).parameters.(key).type`	`string`	The value type for this schema. A list of values can be found at the "type" section in the JSON Schema.
`resources.(key).methods.(key).parameters.(key).$ref`	`string`	A reference to another schema. The value of this property is the "ID" of another schema.
`resources.(key).methods.(key).parameters.(key).description`	`string`	A description of this object.
`resources.(key).methods.(key).parameters.(key).default`	`string`	The default value of this property (if one exists).
`resources.(key).methods.(key).parameters.(key).required`	`boolean`	Whether the parameter is required.
`resources.(key).methods.(key).parameters.(key).format`	`string`	An additional regular expression or key that helps constrain the value. For more details see the Type and Format Summary.
`resources.(key).methods.(key).parameters.(key).pattern`	`string`	The regular expression this parameter must conform to.
`resources.(key).methods.(key).parameters.(key).minimum`	`string`	The minimum value of this parameter.
`resources.(key).methods.(key).parameters.(key).maximum`	`string`	The maximum value of this parameter.
`resources.(key).methods.(key).parameters.(key).enum[]`	`list`	Values this parameter may take (if it is an enum).
`resources.(key).methods.(key).parameters.(key).enumDescriptions[]`	`list`	The descriptions for the enums. Each position maps to the corresponding value in the `enum` array.
`resources.(key).methods.(key).parameters.(key).repeated`	`boolean`	Whether this parameter may appear multiple times.
`resources.(key).methods.(key).parameters.(key).location`	`string`	Whether this parameter goes in the query or the path for REST requests.
`resources.(key).methods.(key).parameters.(key).properties`	`object`	If this is a schema for an object, list the schema for each property of this object.
`resources.(key).methods.(key).parameters.(key).properties.(key)`	`nested object`	A single property of this object. The value is itself a JSON Schema object describing this property.
`resources.(key).methods.(key).parameters.(key).additionalProperties`	`nested object`	If this is a schema for an object, this property is the schema for any additional properties with dynamic keys on this object.
`resources.(key).methods.(key).parameters.(key).items`	`nested object`	If this is a schema for an array, this property is the schema for each element in the array.
`resources.(key).methods.(key).parameters.(key).annotations`	`object`	Additional information about this property.
`resources.(key).methods.(key).parameters.(key).annotations.required[]`	`list`	A list of methods that require this property on requests.
`resources.(key).methods.(key).parameterOrder[]`	`list`	Ordered list of required parameters. This serves as a hint to clients on how to structure their method signatures. The array is ordered such that the most significant parameter appears first.
`resources.(key).methods.(key).request`	`object`	The schema for the request.
`resources.(key).methods.(key).request.$ref`	`string`	Schema ID for the request schema.
`resources.(key).methods.(key).response`	`object`	The schema for the response.
`resources.(key).methods.(key).response.$ref`	`string`	Schema ID for the response schema.
`resources.(key).methods.(key).scopes[]`	`list`	OAuth 2.0 scopes applicable to this method.
`resources.(key).methods.(key).supportsMediaDownload`	`boolean`	Whether this method supports media downloads.
`resources.(key).methods.(key).supportsMediaUpload`	`boolean`	Whether this method supports media uploads.
`resources.(key).methods.(key).mediaUpload`	`object`	Media upload parameters.
`resources.(key).methods.(key).mediaUpload.accept[]`	`list`	MIME Media Ranges for acceptable media uploads to this method.
`resources.(key).methods.(key).mediaUpload.maxSize`	`string`	Maximum size of a media upload, such as "1MB", "2GB" or "3TB".
`resources.(key).methods.(key).mediaUpload.protocols`	`object`	Supported upload protocols.
`resources.(key).methods.(key).mediaUpload.protocols.simple`	`object`	Supports uploading as a single HTTP request.
`resources.(key).methods.(key).mediaUpload.protocols.simple.multipart`	`boolean`	`true` if this endpoint supports upload multipart media.
`resources.(key).methods.(key).mediaUpload.protocols.simple.path`	`string`	The URI path to be used for upload. Should be used in conjunction with the `rootURL` property at the API-level.
`resources.(key).methods.(key).mediaUpload.protocols.resumable`	`object`	Supports the Resumable Media Upload protocol.
`resources.(key).methods.(key).mediaUpload.protocols.resumable.multipart`	`boolean`	`true` if this endpoint supports uploading multipart media.
`resources.(key).methods.(key).mediaUpload.protocols.resumable.path`	`string`	The URI path to be used for upload. Should be used in conjunction with the `rootURL` property at the API-level.
`resources.(key).methods.(key).supportsSubscription`	`boolean`	Whether this method supports subscriptions.
`resources.(key).resources`	`object`	Sub-resources on this resource.
`resources.(key).resources.(key)`	`nested object`	Description for any sub-resources on this resource.