Canaux REST

Les canaux REST offrent plusieurs points intéressants qui facilitent le développement d'API basées sur JSON.

  • Les chemins URL peuvent inclure des motifs
  • Les paramètres URL peuvent faire partie de l'entrée d'un service.
  • Les utilisateurs peuvent décider quels types de paramètres ont la priorité les uns sur les autres.
  • L'accès à un canal peut être limité à un verbe HTTP sélectionné.
  • Le format des données peut être défini en JSON, XML ou aucun format particulier.
  • Les services peuvent réagir uniquement aux verbes HTTP choisis par l'utilisateur (documentés dans un chapitre séparé).
  • Le contrôle d'accès basé sur les rôles peut être utilisé pour attribuer des rôles et des actions aux applications clientes et aux verbes HTTP qu'elles sont autorisées à utiliser.

Notez que pour tirer parti des modèles de chemin d'accès et des paramètres d'URL, un service doit utiliser les éléments suivants SimpleIO. C'est ce qu'utilise le service ci-dessous.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class GetBalance(Service):

    class SimpleIO:
        input_required  = 'cust_no', 'account_no'
        output_required = 'balance', 'currency'

    def handle(self):

        # Confirm input was received
        self.logger.info('Customer: %s', self.request.input.cust_no)
        self.logger.info('Account: %s', self.request.input.account_no)

        # Produce sample output
        self.response.payload.balance = '357.19'
        self.response.payload.currency = 'EUR'

Nettoyer les URL avec des modèles de path

Un exemple d'URL propre peut être http://localhost:11223/customer/balance/37172/HAZDM017/ et pour le configurer à partir de l'administrateur Web, il faut remplir un formulaire pour créer un REST comme suit. Notez que le chemin de l'URL contient des paramètres compris entre { et }.

Le service peut maintenant être invoqué à l'aide d'une URL propre et agréable :

$ curl http://localhost:11223/customer/balance/37172/HAZDM017/ ; echo
{"response": {"currency": "EUR", "balance": "357.19"}}
$

Et le contenu du server.log confirme que l'input a bien été reçue:

INFO - Customer: 37172
INFO - Account: HAZDM017

Paramètres dans le path de la requête

Le même service peut être monté sur un autre canal qui permettra aux applications clientes d'utiliser des paramètres de requête plutôt que des paramètres intégrés dans un path.

$ curl "http://localhost:11223/customer/balance?cust_no=198271&account_no=KMZQ62M" ; echo
{"response": {"currency": "EUR", "balance": "357.19"}}
$

Encore une fois, le server.log confirme que l'input était la même :

INFO - Customer: 198271
INFO - Account: KMZQ62M

Utilisation du payload JSON

Notez qu'il est toujours possible d'invoquer le même service en utilisant des données utiles JSON en entrée :

$ curl http://localhost:11223/customer/balance -d \
    '{"cust_no":"38631", "account_no":"JZM92KH"}' ; echo
{"response": {"currency": "EUR", "balance": "357.19"}}
$
INFO - Customer: 38631
INFO - Account: JZM92KH

Priorité des paramètres

Étant donné qu'il existe 3 sources de paramètres - la charge utile, le chemin d'accès à l'URL et la chaîne de requête - un mécanisme de résolution de priorité à deux niveaux permet de décider lesquels ont la priorité sur un autre s'il arrive que le même paramètre soit fourni plus d'une fois en entrée.

La "priorité des paramètres de l'URL" peut être un QS sur le chemin ou un chemin sur QS. Si c'est "QS over path", alors les paramètres de la chaîne de requête sont préférés aux paramètres trouvés en utilisant les paramètres du chemin. Avec "Path over QS", c'est l'inverse.

Une fois qu'il a été décidé que les paramètres de chaîne de requête ou de chemin sont prioritaires, leur priorité sur les données utiles est décidée.

La "priorité des paramètres" peut être URL sur message ou Message sur URL. Avec "URL over message", les paramètres résultant de la décision précédente ont la priorité sur les données utiles dans le message. Avec "Message over URL", c'est l'inverse.

Méthodes HTTP

Un canal peut être configuré pour accepter uniquement une méthode HTTP arbitraire. Les requêtes soumises à l'aide de toute autre méthode seront rejetées.

Un service peut restreindre la gamme des méthodes supportées même si un canal donné ne le fait pas ; cependant, une fois qu'un canal a choisi le verbe auquel il doit réagir, le service ne pourra pas en utiliser d'autres.

Format des données

Un canal HTTP peut être configuré pour recevoir en entrée des données JSON, XML ou HL7. Cela permet à Zato d'extraire automatiquement les paramètres du message entrant et de sérialiser la réponse à partir de la charge utile produite par un service.

Il est également possible de ne pas définir de format de données spécifique. Par exemple, si vous utilisez [HL7 v2] (https://en.wikipedia.org/wiki/HL7), le service analysera lui-même le message.