Document de découverte

Les documents de découverte sont disponibles pour des versions spécifiques de la plupart des API. Ils décrivent pour chacune d'elles la surface de l'API, comment y accéder, ainsi que la structure des requêtes et des réponses de l'API. Les informations fournies par le document de découverte incluent des propriétés au niveau de l'API telles qu'une description de l'API, des schémas de ressources, des champs d'application d'authentification et des méthodes.

Méthodes

Le document de découverte porte sur la méthode RESTful permettant d'appeler une API. La méthode discovery.apis.list renvoie la liste de toutes les API compatibles avec le service de découverte des API Google, y compris les URL permettant de récupérer les documents de découverte basés sur l'architecture REST.

list
Récupérez la liste des API compatibles avec ce point de terminaison.

Représentations d'une ressource

{
  "kind": "discovery#restDescription",
  "discoveryVersion": "v1",
  "id": string,
  "name": string,
  "canonicalName": 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",
  "endpoints": [
    {
      "endpointUrl": string,
      "location": string,
      "deprecated": boolean,
      "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
        ]
      }
    }
  },
  "auth": {
    "oauth2": {
      "scopes": {
        (key): {
          "description": string
        }
      }
    }
  },
  "features": [
    string
  ],
  "schemas": {
    (key): {
      "id": string,
      "type": string,
      "$ref": string,
      "description": string,
      "default": string,
      "required": boolean,
      "deprecated": boolean,
      "format": string,
      "pattern": string,
      "minimum": string,
      "maximum": string,
      "enum": [
        string
      ],
      "enumDescriptions": [
        string
      ],
      "enumDeprecated": [
        boolean
      ],
      "repeated": boolean,
      "location": string,
      "properties": {
        (key): (JsonSchema)
      },
      "additionalProperties": (JsonSchema),
      "items": (JsonSchema),
      "annotations": {
        "required": [
          string
        ]
      }
    }
  },
  "methods": {
    (key): {
      "id": string,
      "path": string,
      "httpMethod": string,
      "description": string,
      "deprecated": boolean,
      "parameters": {
        (key): {
          "id": string,
          "type": string,
          "$ref": string,
          "description": string,
          "default": string,
          "required": boolean,
          "deprecated": boolean,
          "format": string,
          "pattern": string,
          "minimum": string,
          "maximum": string,
          "enum": [
            string
          ],
          "enumDescriptions": [
            string
          ],
          "enumDeprecated": [
            boolean
          ],
          "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,
          "deprecated": boolean,
          "parameters": {
            (key): {
              "id": string,
              "type": string,
              "$ref": string,
              "description": string,
              "default": string,
              "required": boolean,
              "deprecated": boolean,
              "format": string,
              "pattern": string,
              "minimum": string,
              "maximum": string,
              "enum": [
                string
              ],
              "enumDescriptions": [
                string
              ],
              "enumDeprecated": [
                boolean
              ],
              "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
        }
      },
      "deprecated": boolean,
      "resources": {
        (key): (RestResource)
      }
    }
  }
}
Nom de la propriété Valeur Description
kind string Genre de cette réponse. Chaîne fixe discovery#restDescription.
discoveryVersion string Indiquez la version de l'API Discovery utilisée pour générer ce document.
id string ID du document de découverte de l'API. Par exemple, urlshortener:v1.
name string Nom de l'API. Par exemple, urlshortener.
canonicalName string Nom canonique de l'API. Par exemple, Url Shortener.
version string Version de l'API. Par exemple, v1.
revision string Révision de l'API.
title string Intitulé de l'API. Par exemple, "API Google Url Shortener".
description string Description de cette API.
icons object Liens vers des icônes de 16 x 16 et 32 x 32 représentant l'API.
icons.x16 string URL de l'icône de 16 x 16.
icons.x32 string URL de l'icône de 32 x 32.
labels[] list Étiquettes associées à l'état de cette API. Les valeurs valides incluent limited_availability ou deprecated.
protocol string Protocole décrit dans le document. Par exemple, REST.
rootUrl string URL racine sous laquelle tous les services d'API sont hébergés.
endpoints[] list Liste des objets de point de terminaison basés sur l'emplacement pour cette API. Chaque objet contient l'URL du point de terminaison, son emplacement, sa description et son état d'obsolescence.
endpoints[].endpointUrl string URL de l'hôte cible du point de terminaison.
endpoints[].location string Emplacement du point de terminaison.
endpoints[].description string Chaîne décrivant l'hôte désigné par l'URL.
endpoints[].deprecated boolean Indique si ce point de terminaison est obsolète.
parameters object Paramètres communs s'appliquant à toutes les API.
parameters.(key) nested object Description d'un seul paramètre.
parameters.(key).id string Identifiant unique de ce schéma.
parameters.(key).type string Type de valeur de ce schéma. La liste des valeurs est disponible dans la section "type" du schéma JSON.
parameters.(key).$ref string Référence à un autre schéma. La valeur de cette propriété correspond à l'ID d'un autre schéma.
parameters.(key).description string Description de cet objet.
parameters.(key).default string Valeur par défaut de cette propriété (le cas échéant).
parameters.(key).required boolean Indique si le paramètre est obligatoire.
parameters.(key).format string Expression régulière ou clé supplémentaire permettant de limiter la valeur. Pour en savoir plus, consultez le récapitulatif des types et des formats.
parameters.(key).pattern string Expression régulière à laquelle ce paramètre doit se conformer.
parameters.(key).minimum string Valeur minimale de ce paramètre.
parameters.(key).maximum string Valeur maximale de ce paramètre.
parameters.(key).enum[] list Valeurs que ce paramètre peut prendre (s'il s'agit d'une énumération).
parameters.(key).enumDescriptions[] list Descriptions des énumérations. Chaque position correspond à la valeur associée dans le tableau d'énumération.
parameters.(key).repeated boolean Indique si ce paramètre peut apparaître plusieurs fois.
parameters.(key).location string Indique si ce paramètre doit figurer dans la requête ou dans le chemin d'accès pour les requêtes REST.
parameters.(key).properties object S'il s'agit d'un schéma pour un objet, répertoriez-le pour chaque propriété de cet objet.
parameters.(key).properties.(key) nested object Propriété unique de cet objet. La valeur est elle-même un objet de schéma JSON décrivant cette propriété.
parameters.(key).additionalProperties nested object S'il s'agit d'un schéma pour un objet, cette propriété correspond au schéma de toutes les propriétés supplémentaires comportant des clés dynamiques sur cet objet.
parameters.(key).items nested object S'il s'agit d'un schéma pour un tableau, cette propriété correspond au schéma de chaque élément du tableau.
parameters.(key).annotations object Informations supplémentaires concernant cette propriété.
parameters.(key).annotations.required[] list Liste des méthodes qui nécessitent cette propriété dans les requêtes.
auth object Informations d'authentification.
auth.oauth2 object Informations d'authentification OAuth 2.0.
auth.oauth2.scopes object Champs d'application OAuth 2.0 disponibles.
auth.oauth2.scopes.(key) object Valeur du champ d'application.
auth.oauth2.scopes.(key).description string Description du champ d'application.
features[] list Liste des fonctionnalités compatibles avec cette API.
schemas object Schémas de cette API.
schemas.(key) nested object Description d'un schéma individuel.
schemas.(key).id string Identifiant unique de ce schéma. Exemple : URL
schemas.(key).type string Type de valeur pour ce schéma. La liste des valeurs est disponible dans la section "type" du schéma JSON.
schemas.(key).$ref string Référence à un autre schéma. La valeur de cette propriété correspond à l'ID d'un autre schéma.
schemas.(key).description string Description de cet objet.
schemas.(key).default string Valeur par défaut de cette propriété (le cas échéant).
schemas.(key).required boolean Indique si le paramètre est obligatoire.
schemas.(key).deprecated boolean Indique si ce schéma est obsolète.
schemas.(key).format string Expression régulière ou clé supplémentaire permettant de limiter la valeur. Pour en savoir plus, consultez le récapitulatif des types et des formats.
schemas.(key).pattern string Expression régulière à laquelle ce paramètre doit se conformer.
schemas.(key).minimum string Valeur minimale de ce paramètre.
schemas.(key).maximum string Valeur maximale de ce paramètre.
schemas.(key).enum[] list Valeurs que ce paramètre peut prendre (s'il s'agit d'une énumération).
schemas.(key).enumDescriptions[] list Descriptions des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
schemas.(key).enumDeprecated[] list État d'obsolescence des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
schemas.(key).repeated boolean Indique si ce paramètre peut apparaître plusieurs fois.
schemas.(key).location string Indique si ce paramètre doit figurer dans la requête ou dans le chemin d'accès aux requêtes REST.
schemas.(key).properties object S'il s'agit d'un schéma pour un objet, répertoriez-le pour chaque propriété de cet objet.
schemas.(key).properties.(key) nested object Propriété unique de cet objet. La valeur est elle-même un objet de schéma JSON décrivant cette propriété.
schemas.(key).additionalProperties nested object S'il s'agit d'un schéma pour un objet, cette propriété correspond au schéma de toutes les propriétés supplémentaires comportant des clés dynamiques sur cet objet.
schemas.(key).items nested object S'il s'agit d'un schéma pour un tableau, cette propriété correspond au schéma de chaque élément du tableau.
schemas.(key).annotations object Informations supplémentaires concernant cette propriété.
schemas.(key).annotations.required[] list Liste des méthodes qui nécessitent cette propriété dans les requêtes.
methods object Méthodes au niveau de l'API pour cette API.
methods.(key) nested object Description d'une méthode individuelle.
methods.(key).id string Identifiant unique pour cette méthode. Cette propriété peut être utilisée pour mettre en correspondance des méthodes entre différentes versions de découverte.
methods.(key).description string Description de cette méthode.
methods.(key).deprecated boolean Indique si cette méthode est obsolète.
methods.(key).parameters object Informations sur tous les paramètres de cette méthode.
methods.(key).parameters.(key) nested object Informations sur un seul paramètre de cette méthode.
methods.(key).parameters.(key).id string Identifiant unique de ce schéma.
methods.(key).parameters.(key).type string Type de valeur pour ce schéma.  La liste des valeurs est disponible dans la section "type" du schéma JSON.
methods.(key).parameters.(key).$ref string Référence à un autre schéma. La valeur de cette propriété correspond à l'ID d'un autre schéma.
methods.(key).parameters.(key).description string Description de cet objet.
methods.(key).parameters.(key).default string Valeur par défaut de cette propriété (le cas échéant).
methods.(key).parameters.(key).required boolean Indique si le paramètre est requis.
methods.(key).parameters.(key).deprecated boolean Indique si le paramètre est obsolète.
methods.(key).parameters.(key).format string Expression régulière ou clé supplémentaire permettant de limiter la valeur. Pour en savoir plus, consultez le récapitulatif des types et des formats.
methods.(key).parameters.(key).pattern string Expression régulière à laquelle ce paramètre doit se conformer.
methods.(key).parameters.(key).minimum string Valeur minimale de ce paramètre.
methods.(key).parameters.(key).maximum string Valeur maximale de ce paramètre.
methods.(key).parameters.(key).enum[] list Valeurs que ce paramètre peut prendre (s'il s'agit d'une énumération).
methods.(key).parameters.(key).enumDescriptions[] list Descriptions des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
methods.(key).parameters.(key).enumDeprecated[] list État d'obsolescence des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
methods.(key).parameters.(key).repeated boolean Indique si ce paramètre peut apparaître plusieurs fois.
methods.(key).parameters.(key).location string Indique si ce paramètre doit figurer dans la requête ou dans le chemin d'accès pour les requêtes REST.
methods.(key).parameters.(key).properties object S'il s'agit d'un schéma pour un objet, répertoriez-le pour chaque propriété de cet objet.
methods.(key).parameters.(key).properties.(key) nested object Propriété unique de cet objet. La valeur est elle-même un objet de schéma JSON décrivant cette propriété.
methods.(key).parameters.(key).additionalProperties nested object S'il s'agit d'un schéma pour un objet, cette propriété correspond au schéma de toutes les propriétés supplémentaires comportant des clés dynamiques sur cet objet.
methods.(key).parameters.(key).items nested object S'il s'agit d'un schéma pour un tableau, cette propriété correspond au schéma de chaque élément du tableau.
methods.(key).parameters.(key).annotations object Informations supplémentaires concernant cette propriété.
methods.(key).parameters.(key).annotations.required[] list Liste des méthodes pour lesquelles cette propriété est requise dans les requêtes.
methods.(key).parameterOrder[] list Liste triée des paramètres obligatoires. Cela sert d'indice pour les clients sur la façon de structurer leurs signatures de méthode. Le tableau est trié de sorte que le paramètre le plus important apparaisse en premier.
methods.(key).scopes[] list Champs d'application OAuth 2.0 applicables à cette méthode.
methods.(key).supportsMediaDownload boolean Indique si cette méthode est compatible avec le téléchargement de contenus multimédias.
methods.(key).supportsMediaUpload boolean Indique si cette méthode est compatible avec l'importation de contenus multimédias.
methods.(key).mediaUpload object Paramètres d'importation de contenus multimédias.
methods.(key).mediaUpload.accept[] list Plages de médias MIME pour les importations de contenus multimédias acceptables dans cette méthode.
methods.(key).mediaUpload.maxSize string Taille maximale de l'importation d'un contenu multimédia, telle que "1 Mo", "2 Go" ou "3 To".
methods.(key).supportsSubscription boolean Indique si cette méthode est compatible avec les abonnements.
baseUrl string [OBSOLÈTE] URL de base des requêtes REST.
basePath string [OBSOLÈTE] Chemin de base des requêtes REST.
servicePath string Chemin de base de toutes les requêtes REST.
batchPath string Chemin d'accès aux requêtes REST par lot.
methods.(key).path string Chemin d'URI de cette méthode REST. À utiliser conjointement avec la propriété servicePath au niveau de l'API.
methods.(key).httpMethod string Méthode HTTP utilisée par cette méthode.
methods.(key).request object Schéma de la requête.
methods.(key).request.$ref string ID du schéma de requête.
methods.(key).request.parameterName string [OBSOLÈTE] Certaines API comportent ce champ pour des raisons de rétrocompatibilité. Vous pouvez l'ignorer sans problème.
methods.(key).response object Schéma de la réponse.
methods.(key).response.$ref string ID du schéma de réponse.
methods.(key).mediaUpload.protocols object Protocoles d'importation compatibles
methods.(key).mediaUpload.protocols.simple object Accepte l'importation dans une seule requête HTTP.
methods.(key).mediaUpload.protocols.simple.multipart boolean La valeur est "true" si ce point de terminaison est compatible avec l'importation de contenus multimédias en plusieurs parties.
methods.(key).mediaUpload.protocols.simple.path string Chemin d'URI à utiliser pour l'importation. À utiliser conjointement avec la propriété rootURL au niveau de l'API.
methods.(key).mediaUpload.protocols.resumable object Compatible avec le protocole d'importation de contenu multimédia avec reprise.
methods.(key).mediaUpload.protocols.resumable.multipart boolean true si ce point de terminaison permet d'importer des contenus multimédias en plusieurs parties.
methods.(key).mediaUpload.protocols.resumable.path string Chemin d'URI à utiliser pour l'importation. À utiliser conjointement avec la propriété rootURL au niveau de l'API.
resources object Ressources dans cette API.
resources.(key) nested object Description d'une ressource individuelle. Contient les méthodes et les sous-ressources associées à cette ressource.
resources.(key).methods object Méthodes liées à cette ressource.
resources.(key).methods.(key) nested object Description de toutes les méthodes liées à cette ressource.
resources.(key).methods.(key).id string Identifiant unique pour cette méthode. Cette propriété peut être utilisée pour mettre en correspondance des méthodes entre différentes versions de découverte.
resources.(key).methods.(key).path string Chemin d'URI de cette méthode REST. À utiliser conjointement avec la propriété servicePath au niveau de l'API.
resources.(key).methods.(key).flatPath string Chemin d'URI de cette méthode REST au format (RFC 6570) sans fonctionnalités de niveau 2 ({+var}). Complémentaire à la propriété path.
resources.(key).methods.(key).httpMethod string Méthode HTTP utilisée par cette méthode.
resources.(key).methods.(key).description string Description de cette méthode.
resources.(key).methods.(key).deprecated boolean Indique si cette méthode est obsolète.
resources.(key).methods.(key).parameters object Informations sur tous les paramètres de cette méthode.
resources.(key).methods.(key).parameters.(key) nested object Informations sur un seul paramètre de cette méthode.
resources.(key).methods.(key).parameters.(key).id string Identifiant unique de ce schéma.
resources.(key).methods.(key).parameters.(key).type string Type de valeur pour ce schéma. La liste des valeurs est disponible dans la section "type" du schéma JSON.
resources.(key).methods.(key).parameters.(key).$ref string Référence à un autre schéma. La valeur de cette propriété correspond à l'ID d'un autre schéma.
resources.(key).methods.(key).parameters.(key).description string Description de cet objet.
resources.(key).methods.(key).parameters.(key).default string Valeur par défaut de cette propriété (le cas échéant).
resources.(key).methods.(key).parameters.(key).required boolean Indique si le paramètre est requis.
resources.(key).methods.(key).parameters.(key).deprecated boolean Indique si le paramètre est obsolète.
resources.(key).methods.(key).parameters.(key).format string Expression régulière ou clé supplémentaire permettant de limiter la valeur. Pour en savoir plus, consultez le récapitulatif des types et des formats.
resources.(key).methods.(key).parameters.(key).pattern string Expression régulière à laquelle ce paramètre doit se conformer.
resources.(key).methods.(key).parameters.(key).minimum string Valeur minimale de ce paramètre.
resources.(key).methods.(key).parameters.(key).maximum string Valeur maximale de ce paramètre.
resources.(key).methods.(key).parameters.(key).enum[] list Valeurs que ce paramètre peut prendre (s'il s'agit d'une énumération).
resources.(key).methods.(key).parameters.(key).enumDescriptions[] list Descriptions des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
resources.(key).methods.(key).parameters.(key).enumDeprecated[] list État d'obsolescence des énumérations. Chaque position correspond à la valeur associée dans le tableau enum.
resources.(key).methods.(key).parameters.(key).repeated boolean Indique si ce paramètre peut apparaître plusieurs fois.
resources.(key).methods.(key).parameters.(key).location string Indique si ce paramètre doit figurer dans la requête ou dans le chemin d'accès aux requêtes REST.
resources.(key).methods.(key).parameters.(key).properties object S'il s'agit d'un schéma pour un objet, répertoriez-le pour chaque propriété de cet objet.
resources.(key).methods.(key).parameters.(key).properties.(key) nested object Propriété unique de cet objet. La valeur est elle-même un objet de schéma JSON décrivant cette propriété.
resources.(key).methods.(key).parameters.(key).additionalProperties nested object S'il s'agit d'un schéma pour un objet, cette propriété correspond au schéma de toutes les propriétés supplémentaires comportant des clés dynamiques sur cet objet.
resources.(key).methods.(key).parameters.(key).items nested object S'il s'agit d'un schéma pour un tableau, cette propriété correspond au schéma de chaque élément du tableau.
resources.(key).methods.(key).parameters.(key).annotations object Informations supplémentaires concernant cette propriété.
resources.(key).methods.(key).parameters.(key).annotations.required[] list Liste des méthodes nécessitant cette propriété dans les requêtes.
resources.(key).methods.(key).parameterOrder[] list Liste triée des paramètres obligatoires. Cela sert d'indice pour les clients sur la façon de structurer leurs signatures de méthode. Le tableau est trié de sorte que le paramètre le plus important apparaisse en premier.
resources.(key).methods.(key).request object Schéma de la requête.
resources.(key).methods.(key).request.$ref string ID du schéma de requête.
resources.(key).methods.(key).response object Schéma de la réponse.
resources.(key).methods.(key).response.$ref string ID du schéma de réponse.
resources.(key).methods.(key).scopes[] list Champs d'application OAuth 2.0 applicables à cette méthode.
resources.(key).methods.(key).supportsMediaDownload boolean Indique si cette méthode est compatible avec le téléchargement de contenus multimédias.
resources.(key).methods.(key).supportsMediaUpload boolean Indique si cette méthode est compatible avec l'importation de contenus multimédias.
resources.(key).methods.(key).mediaUpload object Paramètres d'importation de contenus multimédias.
resources.(key).methods.(key).mediaUpload.accept[] list Plages de médias MIME pour les importations de contenus multimédias acceptables dans cette méthode.
resources.(key).methods.(key).mediaUpload.maxSize string Taille maximale de l'importation d'un contenu multimédia, telle que "1 Mo", "2 Go" ou "3 To".
resources.(key).methods.(key).mediaUpload.protocols object Protocoles d'importation compatibles
resources.(key).methods.(key).mediaUpload.protocols.simple object Accepte l'importation dans une seule requête HTTP.
resources.(key).methods.(key).mediaUpload.protocols.simple.multipart boolean true si ce point de terminaison permet d'importer des contenus multimédias en plusieurs parties.
resources.(key).methods.(key).mediaUpload.protocols.simple.path string Chemin d'URI à utiliser pour l'importation. À utiliser conjointement avec la propriété rootURL au niveau de l'API.
resources.(key).methods.(key).mediaUpload.protocols.resumable object Compatible avec le protocole d'importation de contenu multimédia avec reprise.
resources.(key).methods.(key).mediaUpload.protocols.resumable.multipart boolean true si ce point de terminaison permet d'importer des contenus multimédias en plusieurs parties.
resources.(key).methods.(key).mediaUpload.protocols.resumable.path string Chemin d'URI à utiliser pour l'importation. À utiliser conjointement avec la propriété rootURL au niveau de l'API.
resources.(key).methods.(key).supportsSubscription boolean Indique si cette méthode est compatible avec les abonnements.
resources.(key).deprecated boolean Indique si cette ressource est obsolète.
resources.(key).resources object Sous-ressources liées à cette ressource.
resources.(key).resources.(key) nested object Description de toutes les sous-ressources liées à cette ressource.