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 à l'application avec une autre application à l'aide des services Web REST. Cette approche fonctionne parfaitement pour les applications simples ou petites. Lorsque des applications sont plus importantes et que vous souhaitez vous connecter à plusieurs services back-end, vous pouvez introduire par inadvertance des problèmes de sécurité et de performances.

Il est recommandé de commencer à créer une couche d'API façade entre les services back-end externes et l'interface utilisateur pour réduire dans la mesure du 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 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, 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

Créez des ressources pour définir les adresses de l'API. Une ressource est le chemin d'une API. Il possède un type, certaines données qui lui sont associées, une relation avec d'autres ressources et une ou plusieurs méthodes qui y agissent. Une ressource peut se trouver presque sur n'importe quelle image, un fichier texte, une collection 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.

Remarque :
Voir les icônes sous les liens Méthodes ? Chaque fois que vous définissez une méthode pour une ressource, une icône s'affiche sous le lien Méthodes. Utilisez-les comme des raccourcis pour visualiser les méthodes déjà 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 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, c'est-à-dire /mobile/custom/audits/findings.
Indiquez le nom d'affichage, qui est le nom de la ressource à faciliter l'identification dans la documentation d'API.
Les ressources sont répertoriées en fonction de 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 entré 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 de spécifier un 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, le symbole correspondant apparaît sous le lien Méthodes. 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 à cette définition de méthode.

Vous pouvez effacer l'encombrement afin de localiser plus rapidement une ressource en passant en mode compact (elle se trouve à 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 pouvant être effectuées sur une ressource. La page Méthodes affiche une seule 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 voir ses détails.

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

Si la ressource pour laquelle vous définissez des méthodes possède des paramètres de chemin, ils sont affichés au-dessus de l'option Ajouter une méthode.
1. (Facultatif) Cliquez sur Obligatoire si vous voulez que les paramètres de chemin soient transmis à chaque méthode.
  Le nom du paramètre est affiché.
2. Indiquez un nom d'affichage pour le 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, puis sélectionnez la méthode de votre choix.

Une fois que vous avez sélectionné une méthode, celle-ci n'est plus répertoriée dans la liste des méthodes, car vous n'utilisez 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 apparaît en haut de la page pour chaque méthode que vous définissez. Cliquez sur une icône de 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 Ressources principale, 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 à laquelle vous voulez vous connecter le service. 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, qui contient 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. Attribuez au paramètre un nom et un nom d'affichage.
2. Sélectionnez un type de valeur valide : Chaîne, Nombre, Entier, Date ou Booléen.
3. (Facultatif) Entrez la description du paramètre, ainsi qu'un exemple que vous pouvez utiliser lorsque vous testez la validité de l'adresse. Vous pouvez par exemple disposer d'une ressource audits et ajouter un paramètre de requête auditorID qui prend une valeur numérique, et d'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 plusieurs fois le 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 choisie, 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'élément que vous créez, tel qu'une liste de clients ou une 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 support.
1. Sélectionnez le type de support du 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, vous ne devez pas entrer de schéma pour un type d'image), vous avez la possibilité d'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 à l'objectif de la ressource. Cela signifie que les données inutiles qui ne ralentiront que la transmission et peuvent augmenter le potentiel 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. Vous définissez le contenu du message.
3. (Facultatif) Cliquez sur Exemple, puis 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. Les données mock permettent de vérifier le comportement de vos méthodes. L'exemple montre les valeurs de simulation pour les données envoyées dans le corps du message, comme 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

Selon la demande, il se peut que vous ayez besoin d'une réponse. Une réponse décrit le processus de renvoi de résultats à partir du service. Vous pouvez définir une réponse pour vérifier que les données demandées ont été renvoyées ou 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 principale différence réside dans le fait que vous devrez sélectionner un code de statut pour indiquer le résultat de la connexion.

Cliquez sur Réponse pour définir une ou plusieurs réponses.
Cliquez sur Ajouter une réponse et sélectionnez le code de statut que vous souhaitez renvoyer.
Un code de statut de 200 est fourni par défaut mais si ce n'est pas le 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'une redirection s'est produite.
- 4 xx indique qu'une erreur utilisateur s'est produite.
- 5 xx indique qu'une erreur de serveur s'est produite.
Pour aider l'utilisateur à comprendre la raison d'une erreur potentielle dans l'API que vous configurez, utilisez un code de statut HTTP, qui correspond le mieux à la situation de l'erreur.
Indiquer la description du code.
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, 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 tout comme vous l'avez spécifié pour le corps de la demande.
1. Pour le type de support basé sur du texte (par exemple, application/json ou text/xml), cliquez sur Schéma pour entrer un schéma (au format JSON) pour le corps.
  Comme pour le corps de la demande, ajoutez uniquement des données pertinentes au corps de la réponse. N'incluez pas plus de données que celles dont vous avez besoin pour l'opération.
2. Cliquez sur Exemple afin d'ajouter des données mock (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 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 attribuer un nom à votre paramètre.
4. Pour le type de support basé sur une image (par exemple, image/png), vous n'avez rien à faire car il n'y a aucun schéma ni 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 201 indiquant qu'une ressource a été créée. Cet exemple montre également le format de réponse renvoyée application/json, un en-tête Location 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 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 passer à une autre page du concepteur d'API pour créer une racine, des types de ressource ou des caractéristiques, ou ajouter de 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 REST Connector

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

Pour obtenir une API de connecteur de travail de base, vous pouvez fournir exactement un nom pour l'API de connecteur et une URL pour le service externe.

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

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

Vous devez créer une API et une implémentation personnalisées pour permettre à vos applications d'appeler les API du 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é.

Configuration d'un connecteur de base

Vous pouvez créer un connecteur opérationnel en complétant les deux premières pages de l'assistant API REST Connector.

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 la nouvelle API de connecteur REST en fournissant les informations suivantes :
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é à la fin de l'URI de base relatif en tant que nom de ressource pour l'API de connecteur. L'URI de base est visible sous le champ Nom de l'API.
  
  A l'exception d'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 sera 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 de temporisation :
- Temporisation de lecture HTTP : durée maximale (en millisecondes) qui peut être passée à attendre la lecture des données. Si vous n'indiquez aucune valeur, la valeur par défaut, 20 secondes, est appliquée.
- Temporisation de connexion HTTP : durée (en millisecondes) de la connexion à l'URL distante. La valeur 0mms indique qu'une temporisation infinie est autorisée.
  
  Les valeurs de temporisation HTTP doivent être inférieures à la stratégie Network_HttpRequestTimeout, qui a une valeur par défaut de 40,000 ms.
  
  Remarque :
  Si vous disposez du rôle d'administrateur de cloud mobile en plus du rôle de développeur de service, vous pouvez ouvrir le fichier policies.properties afin de voir la valeur des stratégies réseau pour l'environnement en cours à partir de la vue Administrateur. Sinon, demandez les valeurs à l'administrateur de cloud mobile.
Cliquez sur Descripteur, puis saisissez les informations de connexion pour le service.

Si vous fournissez 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 Tester, sélectionnez les informations d'identification et de connexion d'authentification, puis effectuez les appels de test au service.

A partir de là, vous pouvez configurer le connecteur de manière plus approfondie en procédant comme suit :

(Si vous avez fourni un descripteur dans la page Descripteur), accédez à la page Ressources et sélectionnez les méthodes des ressources exposé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 de test d'API de connecteur) avant de la publier. En d'autres termes, vous devez également tester l'API personnalisée (avec son implémentation) utilisant cette API de connecteur. Généralement, 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

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 à des ressources sur le service, les appels à un chemin proxy spécifique et les appels pour certains types d'opération (verbes). Cela permet d'appliquer une syntaxe cohérente à la chaîne d'URL, d'enregistrer le développeur du code personnalisé afin qu'il n'ait pas à insérer ces valeurs et de permettre le suivi des différents appels via les analyses.

Vous pouvez créer une ou plusieurs 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 au service existant via le proxy.

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, puis saisissez le nom de la requête ou de l'en-tête et 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, par exemple à 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 demande est généralement effectuée 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 est également effectuée 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 à une règle que vous le souhaitez, mais il est préférable de ne pas surcharger une règle comportant trop d'opérations. Une structure de règle plus simple est plus facile à dépanner.
Développez Ressources et modifiez l'URL distante pour indiquer une ressource à laquelle appliquer la règle. La valeur de l'URL de base est celle que vous avez saisie 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 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 entre en conflit avec une autre règle, la première règle appliquée est prioritaire et la règle conflictuelle 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 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 ont é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

Voici la description de la règle :

Pour GET à 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 se présenterait comme suit :

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

Vous disposez désormais d'un URI de base correspondant au service existant. 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 les stratégies de sécurité et les propriétés de remplacement

Avant de finaliser l'API de connecteur, vous devez savoir 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 vous connectez est l'approche recommandée.

Chaque stratégie de sécurité contient des propriétés, appelées remplacements, que vous pouvez configurer. L'une des raisons pour lesquelles remplacer une propriété de configuration de stratégie est de limiter le nombre de stratégies que vous devez tenir à jour : plutôt que 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 vers la droite pour la déplacer vers la liste Stratégies sélectionnées.
Sélectionnez une seule stratégie pour l'API de connecteur. La description de la stratégie sélectionnée apparaît en dessous de la liste.
Si nécessaire, indiquez des remplacements de la stratégie sélectionnée pour ne pas utiliser les valeurs par défaut.
Pour remplacer une propriété, entrez ou sélectionnez une autre valeur 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 REST Connector.
Cliquez sur Suivant ( > ) pour passer à l'étape suivante.