Implémenter une API personnalisée pour un service REST de façade

Lorsque vous développez une application mobile, vous commencez généralement par la couche d'interface utilisateur, puis vous connectez votre application à une autre application à l'aide de services Web REST. Cette approche fonctionne bien pour les applications petites ou simples. Lorsque les applications sont plus volumineuses et que vous souhaitez vous connecter à plusieurs services back-end, vous pouvez par inadvertance introduire des problèmes de performances et de sécurité.

Il est recommandé de commencer à créer une couche API de façade entre les services back-end externes et l'interface utilisateur afin de réduire autant que possible le nombre d'appels aux services back-end. Par exemple, votre application mobile peut exécuter un seul appel vers la couche d'API de façade qui gère les appels vers d'autres services REST et consolide toutes les données entrantes en une seule réponse à votre application mobile.

Créer une API personnalisée complète

Pour créer une API personnalisée complète à l'aide d'Oracle Mobile Hub.

Cliquez sur et sélectionnez Développement, puis API dans le menu latéral. Si une API a déjà été créée (à l'état Brouillon ou Publié), vous verrez la liste des API. S'il n'existe aucune API personnalisée, une page contenant le bouton Nouvelle API apparaît. Cliquez sur l'API que vous avez déjà créée ou sur Nouvelle API pour commencer.

Définir des adresses

Vous créez des ressources pour définir les adresses de votre API. Une ressource est le nœud d'une API. Il a un type, des données qui lui sont associées, une relation avec d'autres ressources et contient une ou plusieurs méthodes qui agissent sur lui. Une ressource peut être presque n'importe quoi : une image, un fichier texte, un ensemble d'autres ressources, une transaction logique, une procédure, etc.

Cliquez sur le lien de navigation Adresses pour commencer.
Cliquez sur Nouvelle ressource et ajoutez des informations de base.

Chaque fois que vous cliquez sur Nouvelle ressource, vous créez une ressource de niveau supérieur (racine). Si vous voulez ajouter une ressource enfant (imbriquée), cliquez sur Ajouter (+) en regard de la ressource de niveau supérieur. Cliquez sur X pour supprimer une ressource.

Remarques :
Voir les icônes sous les liens Methods ? Chaque fois que vous définissez une méthode pour une ressource, une icône correspondante apparaît sous le lien Methods. Utilisez-les comme raccourcis pour voir quelles méthodes ont déjà été définies pour une ressource. Cliquez sur une icône pour accéder directement à sa définition sur la page Méthodes.
Fournissez le chemin de la ressource, qui est l'URI (relatif à l'URI de base). Par exemple, si l'URI de base est /mobile/custom/audits/, vous pouvez ajouter la ressource findings, à savoir /mobile/custom/audits/findings.
Indiquez le nom d'affichage, qui est le nom de la ressource permettant de l'identifier facilement dans la documentation de l'API.
Les ressources sont répertoriées par leur nom d'affichage sur le côté gauche de la page Test d'API.
Entrez une description succincte de la ressource.

Une fois que vous avez saisi une description, l'URI s'affiche sous le champ de description.
(Facultatif) Indiquez un type de ressource RAML, qui est le type de ressource (resourcesType:). Vous n'avez pas besoin d'indiquer un type de ressource. Si vous souhaitez utiliser un type de ressource mais que vous n'en avez pas défini, cliquez sur le lien Types et définissez-en un.

Lorsque vous créez une méthode pour une ressource, un symbole correspondant à cette méthode apparaît sous le lien Methods. Vous pouvez immédiatement voir quelles méthodes sont définies pour une ressource si vous devez examiner une définition de ressource. Cliquez sur une icône pour accéder directement à la définition de la méthode.

Vous pouvez effacer l'encombrement pour localiser une ressource plus rapidement en passant au mode compact (à droite de Nouvelle ressource). L'affichage compact masque la description, le type et le chemin de la ressource.

Ajout de méthodes à vos ressources

Les méthodes sont des actions qui peuvent être effectuées sur une ressource. La page Methods (Méthodes) indique une méthode à la fois. Après avoir défini au moins deux méthodes, vous pouvez cliquer sur l'icône d'une méthode en haut de la page pour en voir les détails.

Ajoutez des méthodes à la ressource en cliquant sur Méthodes.

Si la ressource pour laquelle vous définissez des méthodes a des paramètres de chemin, ils sont affichés au-dessus de Ajouter une méthode.
1. (Facultatif) Cliquez sur Obligatoire pour transmettre les paramètres de chemin avec chaque méthode.
  Le nom du paramètre s'affiche.
2. Indiquez le nom d'affichage du paramètre et l'exemple de code.
3. Dans la liste déroulante, sélectionnez le type de valeur valide pour le paramètre.
Cliquez sur Ajouter une méthode et sélectionnez la méthode de votre choix.

Une fois que vous avez sélectionné une méthode, elle n'est plus répertoriée dans la liste des méthodes car vous n'utilisez une méthode qu'une seule fois par ressource (par exemple, vous ne pouvez pas définir deux méthodes DELETE pour une seule ressource). Une icône pour chaque méthode que vous définissez s'affiche en haut de la page. Cliquez sur l'icône d'une méthode pour accéder directement à sa définition.
(Facultatif) Entrez une brève description de la méthode dans le champ Description.
(Facultatif) Entrez le nom d'affichage de la méthode.
(Facultatif) Indiquez les caractéristiques à appliquer à la méthode.

Si aucune caractéristique de ressource n'est définie, cliquez sur Adresses pour revenir à la page principale Ressources, puis cliquez sur le lien Caractéristiques pour en définir une. Les caractéristiques vous permettent de définir un ensemble d'opérations similaires.

Après avoir défini des méthodes pour la ressource, vous pouvez définir les demandes et les réponses pour ces méthodes.

Définir une demande pour la méthode

Maintenant que vous avez sélectionné une méthode, définissez la demande du service auquel vous souhaitez vous connecter. Par exemple, si vous avez sélectionné une méthode POST, vous pouvez désormais définir les éléments à créer. Pour ce faire, ajoutez des paramètres et un corps de demande contenant la description des données à envoyer au service.

Cliquez sur Demander pour définir une demande.
Cliquez sur Ajouter un paramètre et sélectionnez un type de paramètre : Requête ou En-tête. Sélectionnez Requis si le paramètre est obligatoire pour la méthode.
1. Donnez un nom et un nom d'affichage au paramètre.
2. Sélectionnez un type de valeur valide : Chaîne, Nombre, Entier, Date ou Booléen.
3. (Facultatif) Fournissez une description du paramètre et un exemple que vous pouvez utiliser lorsque vous testez la validité de l'adresse. Par exemple, vous pouvez disposer d'une ressource, audits, et ajouter un paramètre de requête, auditorID, qui prend une valeur numérique, et un autre paramètre, auditName, qui prend une valeur de chaîne :
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  Dans cet exemple, une méthode GET est définie avec les paramètres de requête auditorID et auditName.
4. (Facultatif) Cliquez sur Autres propriétés pour ajouter des propriétés imbriquées au paramètre. Cliquez sur Répéter pour ajouter des multiples du paramètre en cours.
5. Cliquez sur Ajouter un paramètre pour ajouter un autre paramètre de niveau supérieur pour la méthode.
Selon la méthode sélectionnée, cliquez sur Add Media Type et définissez le corps de la méthode. Le corps contient les données que vous envoyez au serveur. Par exemple, si vous définissez une méthode POST, vous devrez définir l'article que vous créez, tel qu'une nouvelle liste de clients ou une nouvelle demande de service. Si vous définissez une méthode GET, vous n'avez pas besoin d'envoyer un corps de méthode, vous n'avez donc pas besoin de spécifier de type de média.
1. Sélectionnez le type de média pour le corps de la méthode, c'est-à-dire le format du message que vous envoyez, tel que du texte, des images ou des formulaires Web.
  En fonction du type (par exemple, si vous n'entrez pas de schéma pour un type d'image), vous pouvez ajouter un schéma, un exemple ou les deux.
  Lors de la définition d'un schéma, ajoutez uniquement les données nécessaires à la finalité de la ressource. Autrement dit, n'ajoutez pas de données inutiles qui ne feront que ralentir la transmission et augmenter le potentiel d'erreurs.
2. (Facultatif) Cliquez sur Schéma et entrez un schéma (au format JSON) dans le panneau de l'éditeur. Un schéma est comme un modèle pour le corps. C'est ce que vous utilisez pour définir le contenu du message.
3. (Facultatif) Cliquez sur Exemple et entrez un exemple (au format JSON) dans le panneau de l'éditeur, qui est utilisé par l'implémentation de simulation comme réponse de simulation pour la méthode. L'utilisation de données de simulation peut vous aider à vérifier le comportement de vos méthodes. L'exemple montre des valeurs de simulation pour les données envoyées dans le corps du message tel que défini dans la méthode POST de la ressource audits :
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
Cliquez sur Add Media Type pour ajouter d'autres types de média. Si vous décidez de ne pas utiliser la méthode, cliquez sur X dans la bannière pour la supprimer.

Définir une réponse pour la méthode

Selon la demande, vous pouvez ou non avoir besoin d'une réponse. Une réponse décrit le processus de renvoi des résultats du service. Vous pouvez définir une réponse qui vérifie que les données que vous avez demandées ont été renvoyées ou une réponse qui confirme que la demande a été reçue ou non. La définition d'une réponse est similaire à la définition d'une demande. La principale différence est que vous devrez sélectionner un code d'état pour vous informer du résultat de la connexion.

Cliquez sur Réponse pour définir des réponses.
Cliquez sur Ajouter une réponse et sélectionnez le code de statut à renvoyer.
Un code de statut de 200 est fourni par défaut, mais s'il ne s'agit pas du code souhaité, sélectionnez-en un dans la liste déroulante.
- 2xx indique que la connexion a réussi.
- 3xx indique qu'une redirection s'est produite.
- 4xx indique qu'une erreur utilisateur s'est produite.
- 5xx indique qu'une erreur de serveur s'est produite.
Pour aider quiconque utilise l'API à comprendre la raison d'une erreur potentielle dans l'API que vous configurez, utilisez un code de statut HTTP pour renvoyer le code qui correspond le mieux à la situation d'erreur.
Fournissez une description de ce que le code désigne.
Cliquez sur Ajouter un en-tête, sélectionnez un en-tête ou une requête de réponse, indiquez le nom de l'en-tête ou de la requête et un nom d'affichage pour l'en-tête, ainsi que le type de valeur valide pour l'en-tête.
Cliquez sur Ajouter un type de support et sélectionnez le format de la réponse. En fonction du type de média sélectionné, vous pouvez ajouter des paramètres, des schémas ou des exemples comme vous l'avez fait pour le corps de la demande.
1. Pour le type de média basé sur du texte (par exemple, application/json ou text/xml), cliquez sur Schéma afin d'entrer un schéma (au format JSON) pour le corps.
  Comme pour le corps de la demande, ajoutez uniquement les données pertinentes au corps de la réponse. N'incluez pas plus de données que nécessaire pour l'opération.
2. Cliquez sur Exemple pour ajouter des données de simulation (au format JSON) pour le corps de la réponse. Utilisez des données de simulation pour vérifier le comportement de vos méthodes avant de les tester avec des données réelles.
3. Pour le type de média basé sur un formulaire (par exemple, multipart/form-data), cliquez sur Ajouter un paramètre et sélectionnez Obligatoire si le paramètre est obligatoire. Indiquez ensuite un nom et sélectionnez un type de valeur. Vous pouvez éventuellement attribuer un nom à votre paramètre.
4. Pour un type de média basé sur une image (par exemple, image/png), vous n'avez rien à faire car il n'y a aucun schéma ou attribut à fournir.

L'exemple suivant montre qu'une réponse pour la méthode POST de la ressource audits a été créée avec un code de statut de 201 indiquant qu'une nouvelle ressource a été créée. L'exemple montre également le format de réponse de retour application/json, un en-tête Location qui a été ajouté et le corps du message contenant les données de simulation :

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

Lorsque vous définissez votre réponse, vous pouvez décider de tester vos adresses ou cliquer sur Adresses dans la barre de navigation pour revenir à la page principale Ressources. Vous pouvez ensuite accéder à une autre page du concepteur d'API pour créer une racine, des types de ressource ou des caractéristiques, ou ajouter une documentation d'API.

Si vous décidez de ne pas utiliser la méthode, cliquez sur X dans la bannière pour la supprimer.

Créer une API de connecteur REST

Utilisez l'assistant API de connecteur REST pour créer, configurer et tester l'API de connecteur.

Pour obtenir une API de connecteur fonctionnelle de base, vous pouvez fournir aussi peu qu'un nom pour l'API de connecteur et une URL pour le service externe.

A partir de là, vous pouvez :

Définissez des règles pour former des demandes ou des réponses spécifiques pour les données auxquelles vous souhaitez accéder.
Configurez les stratégies de sécurité côté client pour le service auquel vous accédez.
Testez la connexion et testez les résultats des appels effectués.

Vous devez créer une API et une implémentation personnalisées pour permettre à vos applications d'appeler les API de connecteur, et générer l'API et l'implémentation automatiquement. Pour ce faire manuellement, vous devez créer une API personnalisée avec les ressources appropriées, puis implémenter le code personnalisé.

Configuration d'un connecteur de base

Vous pouvez créer un connecteur fonctionnel en remplissant les deux premières pages de l'assistant API de connecteur REST.

Cliquez sur et sélectionnez Développement, puis API dans le menu latéral.
Cliquez sur REST (s'il s'agit de la première API de connecteur à créer) ou sur Nouveau connecteur, puis sélectionnez REST dans la liste déroulante.
Identifiez la nouvelle API de connecteur REST en fournissant les éléments suivants :
1. Nom d'affichage de l'API : nom tel qu'il apparaîtra dans la liste des API de connecteur.
2. Nom d'API : nom unique de l'API de connecteur.
  
  Par défaut, ce nom est ajouté à l'URI de base relatif en tant que nom de ressource pour l'API de connecteur. Vous pouvez voir l'URI de base sous le champ Nom d'API.
  
  En dehors d'une nouvelle version de cette API de connecteur, aucune autre API de connecteur ne peut avoir le même nom de ressource.
3. Description courte : cette description sera affichée sur la page Connecteurs lorsque cette API sera sélectionnée.
Cliquez sur Créer.
Sur la page Général de la boîte de dialogue API de connecteur REST, définissez les valeurs de délai d'expiration :
- Délai d'expiration de lecture HTTP : délai maximal (en millisecondes) d'attente de lecture des données. Si vous n'indiquez aucune valeur, la valeur par défaut de 20 secondes est appliquée.
- Délai d'expiration de connexion HTTP : temps (en millisecondes) passé à se connecter à l'URL distante. Une valeur de 0 ms signifie qu'un délai d'expiration infini est autorisé.
  
  Les valeurs de délai d'expiration HTTP doivent être inférieures à la stratégie Network_HttpRequestTimeout, qui a une valeur par défaut de 40 000 ms.
  
  Remarques :
  Si vous disposez d'un rôle d'administrateur de cloud mobile en plus de votre rôle de développeur de service, vous pouvez ouvrir le fichier policies.properties pour afficher la valeur des stratégies réseau pour l'environnement en cours à partir de la vue Administrateur. Sinon, demandez les valeurs à l'administrateur du cloud mobile.
Cliquez sur Descripteur et entrez les informations de connexion du service.

Si vous fournissez une URL de descripteur Swagger, les ressources disponibles sont identifiées et affichées, et vous pouvez sélectionner celles que vous souhaitez.

Remarques :
Seuls les ports d'accès Internet standard 80 et 443 sont pris en charge. La connexion à un service ne peut pas être établie à l'aide d'un port personnalisé.
Cliquez sur Enregistrer.
(Facultatif) Cliquez sur Tester, sélectionnez les informations d'identification d'authentification et effectuez des appels de test vers le service.

Vous pouvez ensuite configurer le connecteur de l'une des manières suivantes :

(Si vous avez fourni un descripteur sur la page Descripteur), accédez à la page Ressources et sélectionnez les méthodes des ressources exposées.
Définir des règles.
Définir les stratégies de sécurité.

Pour vous assurer que la configuration de l'API de connecteur est valide, vous devez la tester minutieusement (pas seulement à partir de la page Test de l'API de connecteur) avant de la publier. Autrement dit, vous devez également tester l'API personnalisée (avec son implémentation) qui utilise cette API de connecteur. Essentiellement, si vous êtes prêt à publier l'API de connecteur, vous devez également être prêt à publier l'API personnalisée qui l'appelle.

Définir des règles

Vous définissez des règles pour définir les interactions entre votre application mobile et un service. Les règles permettent d'ajouter des valeurs de paramètre par défaut pour tous les appels aux ressources du service, les appels à un chemin proxy spécifique et les appels à certains types d'opération (verbes). Cela permet d'appliquer une syntaxe cohérente de la chaîne d'URL, évite au développeur de code personnalisé d'avoir à insérer ces valeurs et permet de suivre les différents appels via des analyses.

Vous pouvez créer des règles. Chaque règle peut comporter des paramètres de type Query et Header.

Si aucune règle n'est appliquée, tous les appels sont transmis via le proxy au service existant.

Si le connecteur n'est pas déjà ouvert, cliquez sur et sélectionnez Développement, puis API dans le menu latéral.
Sélectionnez l'API de connecteur à modifier et cliquez sur Ouvrir.
Sélectionnez Rôles.
Cliquez sur Nouvelle règle.
Cliquez sur Ajouter un paramètre, puis sélectionnez un type de paramètre Requête ou En-tête et entrez le nom de la requête ou de l'en-tête, ainsi que sa valeur.

Remarques :

Bien que vous puissiez définir des règles pour définir certains en-têtes par défaut, ces règles ne sont pas appliquées si le client qui a appelé le connecteur directement via un code personnalisé ou indirectement, comme à partir d'un navigateur Web ou d'une application mobile, a déjà défini les mêmes en-têtes.

En particulier, la définition du format du corps de la demande s'effectue généralement dans le code personnalisé avec l'en-tête Content-Type, et non en tant que règle de connecteur REST. De même, la définition du format du corps de réponse se fait également dans le code personnalisé avec l'en-tête Accept, et non en tant que règle de connecteur REST.

Vous pouvez ajouter autant de paramètres que vous le souhaitez à une règle, mais il est préférable de ne pas surcharger une règle avec trop d'opérations. Une construction de règle plus simple est plus facile à résoudre.
Développez Ressources et modifiez l'URL distante afin de fournir une ressource à laquelle la règle doit être appliquée. La valeur de l'URL de base correspond à ce que vous avez saisi dans l'étape de définition des informations de base et ne peut pas être modifiée.
Sélectionnez Ne pas appliquer aux ressources de niveau inférieur si vous souhaitez que les règles soient appliquées uniquement au niveau de ressource indiqué dans l'URL distante.
(Facultatif) Désélectionnez les méthodes HTTP que vous ne souhaitez pas appliquer aux règles que vous venez de définir. Par défaut, toutes les méthodes sont sélectionnées.
(Facultatif) Cliquez sur Nouvelle règle pour créer une autre règle.

Remarques :

Si vous définissez une règle en conflit avec une autre, la première règle appliquée est prioritaire et la règle en conflit est ignorée.

Lorsque vous avez terminé, cliquez sur Enregistrer, puis sur Suivant (>) pour passer à l'étape suivante de configuration de l'API de connecteur.

La description de la règle que vous venez de définir est affichée dans la bannière Règle juste au-dessus de la section Paramètres par défaut. Par exemple, supposons que les valeurs suivantes aient été fournies :

URL distante = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
URI local = myMapAPI
Règle avec le paramètre suivant : Query:key:A3FAEAJ903022
Méthodes HTTP GET et PUT

La description de la règle se lirait comme suit :

Pour les versions GET à https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle disponibles à l'adresse myMapAPI/directions, incluez Query:key=A3FAEAJ903022.

Si aucune règle n'est créée, la description se lit comme suit :

Pour ALL METHODS à https://maps.googleapis.com/maps/api/directions disponible sur myMapAPI, aucun paramètre par défaut ne sera appliqué.

Vous disposez maintenant d'un URI de base qui correspond au service existant. En utilisant notre exemple :

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle correspond à https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Configurer des stratégies de sécurité et remplacer les propriétés

Avant de finaliser votre API de connecteur, vous devez envisager comment gérer sa sécurité. Vous pouvez utiliser des stratégies de sécurité ou des en-têtes d'autorisation. La sélection d'une stratégie de sécurité décrivant le modèle d'authentification du service auquel vous êtes connecté est l'approche recommandée.

Chaque stratégie de sécurité possède des propriétés, appelées remplacements, que vous pouvez configurer. L'une des raisons de remplacer une propriété de configuration de stratégie est de limiter le nombre de stratégies à gérer : au lieu de créer plusieurs stratégies avec des configurations légèrement différentes, vous pouvez utiliser la même stratégie générique et remplacer des valeurs spécifiques pour répondre à vos besoins.

Pour sélectionner une stratégie de sécurité et définir ses remplacements, procédez comme suit :

Si le connecteur n'est pas déjà ouvert, cliquez sur et sélectionnez Développement, puis API dans le menu latéral.
Sélectionnez l'API de connecteur à modifier et cliquez sur Ouvrir.
Sélectionnez Sécurité.
Sélectionnez la stratégie de sécurité dans la liste des stratégies disponibles et cliquez sur la flèche droite pour la déplacer vers la liste Stratégies sélectionnées.
Sélectionnez une seule stratégie pour l'API de connecteur. Une description d'une stratégie sélectionnée s'affiche sous la liste.
Indiquez les remplacements, le cas échéant, pour la stratégie sélectionnée si vous ne souhaitez pas utiliser les valeurs par défaut.
Pour remplacer une propriété, saisissez ou sélectionnez une valeur autre que la valeur par défaut.
Cliquez sur Enregistrer pour enregistrer votre travail ou sur Enregistrer et fermer pour enregistrer votre travail et quitter l'assistant API de connecteur REST.
Cliquez sur Suivant (>) pour passer à l'étape suivante.