Création d'une spécification de déploiement d'API

Découvrez comment créer une spécification d'API (une définition lisible par la machine d'une API au format JSON) à utiliser avec API Gateway.

Pour pouvoir déployer une API sur une passerelle d'API, vous devez créer une spécification de déploiement d'API. Chaque déploiement d'API comporte une spécification de déploiement d'API.

Chaque spécification de déploiement d'API décrit un ensemble de ressources ainsi que les méthodes (par exemple, GET, PUT) qui peuvent être exécutées sur chaque ressource.

Vous pouvez utiliser une seule passerelle d'API comme composant frontal pour plusieurs services back-end en :

  • créant un seul déploiement d'API sur la passerelle d'API, avec une spécification de déploiement d'API qui définit plusieurs services back-end,
  • créant plusieurs déploiements d'API sur la même passerelle d'API, chacun comportant une spécification de déploiement d'API qui définit des services back-end.

En règle générale, les services back-end sont situés dans le même réseau cloud virtuel que la passerelle d'API sur laquelle vous déployez une API. Ce n'est toutefois pas obligatoire. Dans la spécification de déploiement d'API, vous pouvez décrire des services back-end qui se trouvent sur un sous-réseau public ou privé de votre location, ainsi que des services situés en dehors de votre location (y compris sur le réseau Internet public). Quel que soit leur emplacement, les services back-end doivent pouvoir être acheminés à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée. Par exemple, si le service back-end se trouve sur le réseau Internet public, le réseau cloud virtuel doit disposer d'une passerelle Internet pour permettre à la passerelle d'API d'acheminer les demandes vers le service back-end.

Vous pouvez créer une spécification de déploiement d'API en :

  • utilisant les boîtes de dialogue de la console lors de la création d'un déploiement d'API,
  • utilisant l'éditeur JSON de votre choix pour créer un fichier JSON distinct. Vous pouvez ensuite indiquer ce fichier JSON lorsque vous utilisez la console, l'interface de ligne de commande ou l'API pour créer un déploiement d'API.
  • utilisant un fichier de description d'API que vous téléchargez vers le serveur pour une ressource d'API. Le fichier de description d'API fournit certaines valeurs initiales pour la spécification de déploiement d'API, que vous pouvez modifier et étendre lors du déploiement de la ressource d'API sur une passerelle d'API. Reportez-vous à Création d'une ressource d'API avec une description d'API.

Les instructions contenues dans cette rubrique présentent une spécification de déploiement d'API de base avec un back-end unique, un seul routage et aucune stratégie de demande ou de réponse. Reportez-vous à Exemple de spécification de déploiement d'API avec plusieurs back-ends pour découvrir une spécification de déploiement d'API plus standard qui inclut plusieurs back-ends, chacun comportant des routages.

En outre, vous pouvez ajouter des stratégies de demande et de réponse qui s'appliquent aux routages d'une spécification de déploiement d'API (reportez-vous à Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API).

Utilisation d'un éditeur JSON pour créer une spécification de déploiement d'API dans un fichier JSON distinct

Pour créer une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :

  1. A l'aide de l'éditeur JSON de votre choix, créez la spécification de déploiement d'API dans un fichier JSON au format suivant :

    {
      "requestPolicies": {},
      "routes": [
        {
          "path": "<api-route-path>",
          "methods": ["<method-list>"],
          "backend": {
            "type": "<backend-type>",
            "<backend-target>": "<identifier>"
          },
          "requestPolicies": {}
        }
      ]
    }

    où :

    • "requestPolicies" indique des stratégies facultatives permettant de contrôler le comportement d'un déploiement d'API. Pour appliquer des stratégies à tous les routages dans une spécification de déploiement d'API, placez les stratégies en dehors de la section routes. Pour appliquer les stratégies uniquement à un routage spécifique, placez les stratégies dans la section routes. Reportez-vous à Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API.
    • <api-route-path> spécifie un chemin pour les appels d'API utilisant les méthodes répertoriées vers le service back-end. Le chemin d'accès que vous spécifiez doit remplir les conditions suivantes :

    • <method-list> indique les méthodes acceptées par le service back-end, séparées par des virgules. Par exemple, "GET, PUT".
    • <backend-type> indique le type de service back-end. Valeurs valides : ORACLE_FUNCTIONS_BACKEND, HTTP_BACKEND et STOCK_RESPONSE_BACKEND.
    • <backend-target> et <identifier> spécifient le service back-end. Les valeurs valides pour <backend-target> et <identifier> dépendent de la valeur de <backend-type>, comme suit :

    Par exemple, la spécification de déploiement d'API de base suivante définit une fonction simple sans serveur Hello World dans OCI Functions en tant que back-end unique :

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }

    Pour obtenir un exemple plus complexe qui définit plusieurs back-ends, reportez-vous à Exemple de spécification de déploiement d'API avec plusieurs back-ends.

  2. Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
  3. Utilisez la spécification de déploiement d'API lorsque vous créez ou mettez à jour un déploiement d'API en :

    • spécifiant le fichier JSON dans la console lorsque vous sélectionnez l'option Télécharger une API existante,
    • spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.

    Pour plus d'informations, reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API.

Utilisation d'un fichier de description d'API pour créer une spécification de déploiement d'API

Afin de créer une spécification de déploiement d'API basée sur un fichier de description d'API téléchargé vers le serveur pour une ressource d'API, reportez-vous à Création d'une ressource d'API avec une description d'API.

Le fichier de description d'API fournit certaines valeurs initiales pour la spécification de déploiement d'API, que vous pouvez modifier et étendre lors du déploiement de la ressource d'API sur une passerelle d'API.

Exemple de spécification de déploiement d'API avec plusieurs back-ends

Vous pouvez créer un déploiement d'API unique sur une passerelle d'API, avec une spécification de déploiement d'API qui définit plusieurs services back-end.

Par exemple, la spécification de déploiement d'API suivante définit une fonction simple sans serveur Hello World dans OCI Functions comme un seul back-end, et l'API National Weather Service comme un second back-end.

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/weather",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov"
      }
    }
  ]
}