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.
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 | Notes |
---|---|---|---|
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. |