Implémenter une API personnalisée pour un service REST 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 des services Web REST. Cette approche fonctionne bien pour les applications petites ou simples. Lorsque les applications sont plus grandes et que vous souhaitez vous connecter à plusieurs services back-end, vous pouvez introduire par inadvertance des problèmes de performances et de sécurité.

Il est recommandé de commencer à créer une couche API façade entre les services back-end externes et l'interface utilisateur pour réduire le nombre d'appels aux services back-end, si possible. Par exemple, votre application mobile peut exécuter un seul appel à la couche API façade qui gère les appels vers d'autres services REST et consolide toutes les données entrantes en une seule réponse à l'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, procédez comme suit :

Cliquez sur et sélectionnez Développement, puis des API dans le menu latéral. Si une API a déjà été créée (dans un état Brouillon ou Publié), vous verrez la liste des API. S'il n'existe aucune API personnalisée, une page avec 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 l'objet de l'API. Il comporte un type, des données qui lui sont associées, une relation avec d'autres ressources et contient une ou plusieurs méthodes agissant dessus. Une ressource peut se trouver presque : 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). Pour 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.

Remarque :
Reportez-vous aux icônes sous les liens Méthodes ? Chaque fois que vous définissez une méthode pour une ressource, une icône apparaît sous le lien Méthodes. Utilisez-les en tant que raccourcis pour voir les méthodes déjà définies pour une ressource. Cliquez sur une icône pour accéder directement à sa définition dans la page Méthodes.
Indiquez le chemin de 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, qui est /mobile/custom/audits/findings.
Indiquez le nom d'affichage, qui est un nom de ressource qui facilite l'identification dans la documentation d'API.
Les ressources sont répertoriées par leur nom d'affichage dans la partie gauche de la page Test d'API.
Entrez une description succincte de la ressource.

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

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

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

Ajout de méthodes aux ressources

Les méthodes sont des actions pouvant être effectuées sur une ressource. La page Méthodes affiche 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 visualiser ses détails.

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

Si la ressource que vous définissez comporte des méthodes de paramètres de chemin, elles sont affichées au-dessus d'Ajouter une méthode.
1. (Facultatif) Cliquez sur Obligatoire pour transmettre les paramètres de chemin à chaque méthode.
  Le nom du paramètre est affiché.
2. Indiquez le nom d'affichage du paramètre et un 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 voulue.

Une fois que vous avez sélectionné une méthode, celle-ci ne figure plus 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 est affichée en haut de la page. Cliquez sur une icône de méthode pour accéder directement à sa définition.
(Facultatif) Saisissez une brève description de la méthode dans le champ Description.
(Facultatif) Entrez un nom d'affichage pour 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 sur le lien Traits pour en définir une. Les caractéristiques permettent de définir une collection 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 correspondantes.

Définir une demande pour la méthode

Maintenant que vous avez sélectionné une méthode, définissez la demande à laquelle vous effectuez le service auquel vous voulez vous connecter. Par exemple, si vous avez sélectionné une méthode POST, vous pouvez désormais définir ce que vous souhaitez 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 Demande 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 Obligatoire si le paramètre est obligatoire pour la méthode.
1. Donnez un nom au paramètre et un nom d'affichage.
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 avoir 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 actuel.
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 Ajouter un type de support 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, comme une nouvelle liste de clients ou une demande de service. Si vous définissez une méthode GET, vous n'avez pas besoin d'envoyer de corps de méthode pour ne pas avoir à indiquer de type de support.
1. Sélectionnez le type de support du corps de la méthode, qui est le format du message que vous envoyez, tel que du texte, des images ou des formulaires Web.
  Selon le type (par exemple, vous ne devez pas saisir 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, n'ajoutez que les données nécessaires à l'objectif de la ressource. Cela signifie que vous ne pouvez pas ajouter des données inutiles qui ralentiront uniquement la transmission et susceptibles d'entraîner des 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. 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, utilisé par l'implémentation de simulation comme réponse de simulation pour la méthode. Les données de simulation permettent de vérifier le comportement des méthodes. L'exemple affiche les valeurs de simulation des 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 Ajouter un type de support pour ajouter des types de support supplémentaires. 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

En fonction de la demande, il se peut que vous n'ayez pas besoin d'une réponse. Une réponse décrit le processus de renvoi des résultats à partir du service. Vous pouvez définir une réponse qui vérifie que les données demandées ont été renvoyées ou si vous souhaitez recevoir une réponse indiquant si la demande a été reçue. La définition d'une réponse est semblable à la définition d'une demande. La différence principale est que vous devez sélectionner un code de statut pour vous faire savoir le 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 que vous voulez retourner.
Un code statut de 200 est fourni par défaut, mais s'il ne s'agit pas du code que vous voulez, sélectionnez-en un dans la liste déroulante.
- 2 xx indique qu'une connexion a réussi.
- 3 xx indique qu'un réacheminement a été effectué.
- 4 xx indique qu'une erreur utilisateur est survenue.
- 5 xx indique qu'une erreur de serveur est survenue.
Pour aider l'utilisation de l'API afin de comprendre la raison d'une erreur potentielle dans l'API que vous configurez, utilisez un code de statut HTTP pour renvoyer le code correspondant le mieux à la situation d'erreur.
Fournissez une description des éléments désignés par le code.
Cliquez sur Ajouter un en-tête, sélectionnez un en-tête de réponse ou une requête, indiquez le nom de l'en-tête ou de la requête, ainsi que le nom d'affichage de l'en-tête et 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. Selon le type de support sélectionné, vous pouvez ajouter des paramètres, des schémas ou des exemples de la même manière que pour le corps de la demande.
1. Pour le type de support texte (par exemple, application/json ou text/xml), cliquez sur Schéma pour saisir un schéma (au format JSON) pour le corps.
  Comme avec le corps de demande, n'ajoutez que des données pertinentes au corps de réponse. N'incluez pas plus de données que vous n'avez réellement besoin d'effectuer 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 les données de simulation pour vérifier le comportement de vos méthodes avant le test avec des données réelles.
3. Pour le type de support 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 donner un nom à votre paramètre.
4. Pour le type de support basé sur une image (par exemple, image/png), vous n'avez pas besoin d'effectuer aucune action, car il n'existe aucun schéma ni aucun attribut à fournir.

L'exemple suivant montre qu'une réponse pour la méthode POST de la ressource audits a été créée avec le code de statut 201 indiquant qu'une ressource a été créée avec succès. L'exemple affiche également le format de réponse renvoyée application/json, un en-tête Location qui a été ajouté et le corps du message contenant des 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 choisir de tester vos adresses ou cliquer sur Adresses dans la barre de navigation pour revenir à la page principale Ressources. A partir de là, vous pouvez accéder à une autre page dans le concepteur d'API pour créer une racine, des types de ressource ou des caractéristiques, ou ajouter la 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 de travail de base, vous pouvez fournir un nom minime pour l'API de connecteur et une URL vers le service externe.

A partir de cet emplacement, vous pouvez effectuer les opérations suivantes :

Définissez des règles pour former des demandes ou des réponses spécifiques aux données auxquelles vous voulez accéder.
Configurer des 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 vers celle-ci.

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

Configurer 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 des 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, et dans la liste déroulante, sélectionnez REST.
Identifiez votre nouvelle API de connecteur REST en indiquant les éléments suivants :
1. Nom d'affichage d'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 de l'API de connecteur. Vous pouvez visualiser l'URI de base sous le champ Nom d'API.
  
  Autre qu'une nouvelle version de cette API de connecteur, aucune autre API de connecteur ne peut avoir le même nom de ressource.
3. Brève description : cette description sera affichée sur la page Connecteurs lorsque cette API est sélectionnée.
Cliquez sur Créer.
Dans la page Général de la boîte de dialogue API de connecteur REST, définissez les valeurs d'expiration :
- Temporisation de la lecture HTTP: temps maximal (en millisecondes) nécessaire à l'attente de lecture des données. Si vous n'indiquez aucune valeur, la valeur par défaut de 20 secondes est appliquée.
- Temporisation de connexion HTTP: temps (en millisecondes) consacré à la connexion à l'URL distante. Une valeur de 0mms indique qu'une temporisation infinie est autorisée.
  
  Les valeurs de délai d'expiration HTTP doivent être inférieures à la stratégie Network_HttpRequestTimeout, qui possède une valeur par défaut de 40,000 ms.
  
  Remarque :
  Si vous disposez d'un rôle d'administrateur de Cloud mobile en plus de votre rôle de développeur de services, vous pouvez ouvrir le fichier policies.properties pour voir la valeur des stratégies réseau de l'environnement en cours à partir de la vue Administrateur. Sinon, demandez à l'administrateur Mobile Cloud de saisir les valeurs.
Cliquez sur Descripteur et saisissez les informations de connexion pour le service.

Si vous spécifiez une URL de descripteur Swagger, les ressources disponibles sont identifiées et affichées, et vous pouvez sélectionner celles de votre choix.

Remarque :
Seuls les ports d'accès Internet standard 80 et 443 sont pris en charge. Impossible d'établir la connexion à un service à l'aide d'un port personnalisé.
Cliquez sur Enregistrer.
(Facultatif) Cliquez sur Test, sélectionnez les informations d'identification et de connexion d'authentification, puis effectuez des appels de test vers le service.

A partir de là, vous pouvez configurer le connecteur de l'une des manières suivantes :

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

Pour être sûr que la configuration d'API de connecteur est valide, vous devez la tester de manière approfondie (pas seulement à partir de la page Test d'API de connecteur) avant de la publier. Cela signifie que vous devez également tester l'API personnalisée (avec son implémentation) qui utilise cette API de connecteur. Dans l'essentiel, 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 les règles

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, d'appeler un chemin proxy spécifique et d'appeler pour certains types d'opération (verbes). Cela permet d'assurer une syntaxe cohérente de la chaîne d'URL, d'enregistrer le développeur de code personnalisé sans avoir à insérer ces valeurs et de suivre les différents appels via Analytics.

Vous pouvez créer des règles. Chaque règle peut avoir un ou plusieurs 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, sélectionnez un type de paramètre Requête ou En-tête, et saisissez le nom de la requête ou de l'en-tête, ainsi que sa valeur.

Remarque :

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

En particulier, la définition du format du corps de demande est généralement effectuée dans le code personnalisé avec l'en-tête Content-Type et non comme règle de connecteur REST. De même, la définition du format du corps de réponse dans le code personnalisé avec l'en-tête Accept n'est pas une règle de connecteur REST.

Vous pouvez ajouter autant de paramètres à une règle que vous le souhaitez, mais il est préférable de ne pas surcharger une règle avec un trop grand nombre d'opérations. Une construction de règle plus simple est plus facile à dépanner.
Développez Ressources, puis modifiez l'URL distante afin d'indiquer une ressource à laquelle la règle doit être appliquée. La valeur d'URL de base correspond à ce que vous avez saisi à 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 voulez que les règles ne s'appliquent qu'au niveau de ressource indiqué dans l'URL distante.
(Facultatif) Désélectionnez les méthodes HTTP que vous ne voulez 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.

Remarque :

Si vous définissez une règle qui est en conflit avec une autre règle, 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 la configuration de l'API de connecteur.

La description de la règle que vous venez de définir apparaît dans la bannière Règle, juste au-dessus de la section Paramètres par défaut. Par exemple, supposons que les valeurs suivantes sont 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 est la suivante :

Pour GET vers https://maps.googleapis.com/maps/api/directions/json ?origin=los+angeles&destination=seattle disponible dans myMapAPI/directions, Inclure Query:key=A3FAEAJ903022.

Si aucune règle n'a été créée, la description est la suivante :

Pour ALL METHODS to https / maps.googleapis.com/maps/api/directions disponibles dans myMapAPI , aucun paramètre par défaut ne sera appliqué.

Vous disposez désormais 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 l'API de connecteur, prenez en compte la méthode de gestion de sa sécurité. Vous pouvez utiliser des stratégies de sécurité ou des en-têtes d'autorisation. Sélection d'une stratégie de sécurité qui décrit le modèle d'authentification du service auquel vous vous connectez 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 consiste à limiter le nombre de stratégies que vous devez conserver : au lieu de créer plusieurs stratégies avec des configurations légèrement variées, 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 les remplacements de stratégie, 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 de la stratégie sélectionnée apparaît en dessous de la liste.
Indiquez les valeurs de remplacement, le cas échéant, à la stratégie sélectionnée si vous ne voulez pas utiliser les valeurs par défaut.
Pour remplacer une propriété, entrez ou sélectionnez une valeur autre que celle 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.