Le broker REST – Ajout et utilisation d’une API REST

Bonjour à tous,

Aujourd’hui j’aurai le plaisir de vous parler un peu plus en détails d’un connecteur très puissant pour K2, le broker REST !

Vous le savez sûrement déjà si vous lisez cet article, K2 propose de nombreux connecteurs vers différents LOB (SQL Server, Active Directory, Microsoft Dynamics, Sharepoint et bien d’autres ! ). Ces connecteurs permettent à nos SmartObjects de récupérer et d’envoyer de l’information à de nombreuses sources en proposant aux applications K2 une interface normalisée. Cependant, il peut vous arriver de vouloir communiquer avec un outil non pris en charge (un développement spécifique chez votre client, un outil web de GED…)

C’est à ce moment qu’il faut se poser la bonne question, cet outil expose-t’il certaines de ses APIs via des webservices ? Si oui, K2 pourra s’y intégrer ! Pour les informations sur le broker WCF / SOAP, ce sera dans un autre article, mais nous allons parler ici de l’intégration via le broker REST !

1) Introduction aux WebServices (REST)

Mais du coup, c’est quoi un WebService ? C’est un protocole d’interface web qui va permettre de communiquer et d’échanger des données entre différents systèmes ! Oui, ça semble tout à fait adapté au périmètre de nombreux projets K2 n’est ce pas ?

Ce protocole va mettre à disposition, sur internet ou intranet, des fonctionnalités de votre application, et dans notre cas permettre à K2 d’appeler ces fonctionnalités directement via des SmartObjects.

Le broker REST fonctionne sur un principe assez différent des brokers SQL, CRM, dans la mesure où ces derniers vont aller découvrir les informations du coté externe afin de déterminer les différents paramètres entrants / sortants, méthodes etc. là où le broker REST va se baser sur une définition Swagger (donc une définition qu’on lui fournit, ici, pas de découverte automatique)! Mais qu’est-ce qu’un fichier Swagger me demandez vous, il s’agit en fait d’un format pensé pour faciliter les interactions avec les webservices REST (plus d’infos ici Swagger Editor) qui va contenir toutes les informations nécessaires à la connexion au webservice, ainsi que la structure des entrants / sortants. C’est un fichier Json.

Le site Swagger editor permet de générer des swagger, de tester les méthodes disponibles etc… Par exemple, pour un swagger de test très simple, voilà l’interface récupérée :

Exemple de fichier swagger sur le site Swagger editor

On voit que la description a permis de récupérer deux méthodes (GET et POST).

2) L’API Pet Store et les méthodes des web services REST

Pour les besoins de cet article, j’ai utilisé une API publique mise à disposition par le site mentionné ci-dessus. Vous la trouverez facilement sur le site swagger editor, elle sert de démonstration pour l’utilisation des fichiers swagger. Cet ensemble de méthodes permet la gestion d’une boutique d’animaux de compagnies  (oui, d’où son nom de “Pet Store” pour les moins Anglophones d’entre vous ). Voilà à quoi ressemble un peu cette API

Les différentes méthodes visibles vont être récupérées par K2 via le broker REST et utilisables au travers de SmartObjects ! Il est aussi possible de tester directement les appels sur le site swagger.io, comme expliqué plus haut.

Comme on peut voir, les méthodes sont réparties en catégories (ici, on ne voit que celles pour PET, mais il existe aussi “store” pour le magasin, “user” pour les utilisateurs) qui représentent les différentes entités que nous allons manipuler. Les différentes méthodes des webservices REST sont :

  • GET : permet de récupérer de l’information en provenance de la source
  • POST : permet de créer une nouvelle itération de l’entité au niveau de la source
  • PUT : permet de mettre à jour une itération de l’entité au niveau de la source
  • DELETE : permet de supprimer une itération de l’entité au niveau de la source

Bien évidemment, nous allons le voir rapidement, toutes ces méthodes ne prennent pas les mêmes paramétres entrants et ne restituent pas l’information de la même manière !

Pour soumettre des objets de types complexes, comme la structure d’une nouvelle entrée dans le cas d’un post, il sera quasiment toujours obligatoire de sérialiser les informations pour les transmettres via le body de l’appel web service (en json). Même chose pour récupérer des retours de type liste par exemple, les différentes lignes seront sérialisées et il sera nécessaire de dé-sérialiser le résultat pour l’utiliser. K2 va rendre cette étape très simple en nous fournissant des services objects dédiés à ces opérations de sérialisation / dé-sérialisation. Il suffira de générer les SmartObjects correspondants et de les appeler avant de communiquer avec le WebService.

3) Configuration du broker K2

Le broker REST est accessible via le SmartObject service tester ou via le management, pour une approche plus “K2 Cloud compliant”. Donc je vais présenter la configuration via le K2 Management Site.

Liste des Service Types – K2 Management

Dans la liste des service types, choisir REST et cliquer sur “New Instance”

Configuration de la service instance REST – 1

Renseigner les informations de la service instance :

  • Display Name
  • Description
  • Authentication mode (ici Service Account pour simplifier les interactions, le compte de service K2 sera toujours utilisé)
  • OAuth Resource Name + Audience (pour authentification OAuth)
  • User Name et Password (pour authentification Static)

Configuration de la service instance REST – 2

  • Serialization: include all assembly types : inclus tous les objets permettant de sérialiser l’information peu importe lesquels sont utilisés dans les méthodes exposées
  • Descriptor Location : chemin vers le fichier SWAGGER. Il peut être stocké sur votre environnement K2 ou via un URL Web
  • Append property types : ajout du type dans le nom des propriétés
  • Certificate Search value : Renseigner le nom du certificat si un certificat de sécurité doit être récupéré
  • Certificate store location : localisation du certificat (si la valeur de “Certificate Search Value” est définie à NOT NULL)
  • Certificate Store Name : catégorie de certificat sous laquelle le certificat client est installé. Valeurs valides : AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople et Trusted Publisher. Il est important de noter que le broker REST K2 a seulement été testé pour la catégorie de certificat “My”
  • Break on error : affiche un message d’erreur si l’appel au service ne réussi pas
  • Debugging Enabled : affiche les stack trace
  • Include non Serialized Properties : ajout des propriétés non complexes à la sérialisation
  • Add HTTP Response header property to methods : ajoute une propriété optionnelle pour chaque méthode afin de récupérer une liste de HTTP response headers

Une fois la configuration effectuée K2 sera en mesure de générer des Service Objects correspondants aux méthodes, données à sérialiser etc… comme onpeut le constater sur la copie d’écran ci-dessous avec l’instance du service broker PET Store utilisé en exemple :

L'instance du service broker PET Store
L’instance du service broker PET Store

Ces services objects seront appelés par des SmartObjects afin d’interagir avec vos applications K2 ! N’hésitez pas à partager vos expériences et cas d’utilisations de ce Broker REST !