Couche de transport pour les services REST

Cette rubrique explique comment créer un service REST avec la couche @jutro/transport pour envoyer et recevoir des requêtes HTTP.

Le transport Jutro contient les options suivantes lors de l'envoi et de la réception de requêtes :

HttpRequestBuilder : un wrapper extensible autour de « fetch » pour effectuer des appels REST. Il fournit une série d'outils de résolution « option » pour injecter des options et des en-têtes dans la requête. Il permet également aux encodeurs/décodeurs de transformer les données envoyées et les données reçues, et fournit des rappels pour surveiller le flux requête -> réponse -> exception.
createHttpRequest : crée la requête http à l'aide de HttpRequestBuilder.
createJsonHttpRequest : crée une requête http, mais spécifie le type de contenu JSON, de sorte que le serveur sache sous quelle forme les données qu'il envoie doivent être.
basicAuthOptions : utilisé pour transmettre un nom d’utilisateur et un mot de passe avec authentification de base dans un appel REST. Nous recommandons vivement d’utiliser authTokenHandler avec l'authentification Jutro à la place.
jsonOptions : fournit un en-tête JSON pour les requêtes avec charge utile JSON
langLocaleOptions : fournit les en-têtes gw-language et gw-locale pour les requêtes
analyticsHandler : gère la transmission d'une charge utile d'événement dans la requête http à une eventTopicMap afin qu'il puisse être envoyé à un moteur d'analyse
authTokenHandler : crée des options d'authentification à l'aide d'un jeton porteur de Jutro auth à transmettre à HttpRequestBuilder
zipkinTraceHandler : fournit une extension des options de suivi

createHttpRequest

Pour créer une requête http en tant que service REST :

Importez createHttpRequest à partir de @jutro/transport :

import { createHttpRequest, jsonOptions } from '@jutro/transport';

Créez une variable telles que le restService ci-dessous :

const getRestService = () => {
  const baseUrl = 'https://test.com';

  return createHttpRequest(baseUrl, true).addOptions(jsonOptions).build();
};

Créez une fonction qui exécute la requête :

const postRequest = (url, data) => getRestService().post(url, data);

Vous pouvez également copier des options comme dernier argument de fonctions telles que get() ou post().

const postRequest = (url, data) =>
  getRestService().post(url, data, authTokenHandler);

Si vous souhaitez transmettre des en-têtes personnalisés dans votre requête, vous pouvez les transmettre à l'aide de .addOptions comme ceci :

const getRestService = () => {
  const baseUrl = 'https://test.com';

  return createHttpRequest(baseUrl, 'unauthenticated', true)
    .addOptions({
      headers: { 'Content-Type': 'application/json; charset=UTF-8' },
    })
    .build();
};

Champ de requête d'autorisation - En-tête HTTP

Vous pouvez ajouter un en-tête d'autorisation dans votre service REST à l'aide du authTokenHandler en utilisant les fonctions get() ou post() ou la méthode addHandler().

Dans l'implémentation par défaut, le authTokenHandler obtient le jeton d'authentification et ajoute l'en-tête Authorization, ainsi que le 'GW-Tenant' et le 'GW-User', en fonction des données stockées dans le jeton.

Pour chaque appel d'API qui crée ou modifie un lot de tâches, une ressource ou un locataire, la demande doit contenir les éléments suivants l'ID utilisateur 'GW-User', uid.

Les règles générales suivantes s'appliquent lors de l'utilisation de 'GW-User' dans le cadre d'un appel d'API :

Si l'appel d'API utilise un jeton d'accès utilisateur pour l'autorisation, l'en-tête « GW-User » doit être égal à un sinistre uid dans ce jeton. Un appel sera rejeté si l'en-tête et le jeton sont différents.
Si l'appel d'API utilise un jeton d'accès au service pour l'autorisation, l'en-tête « GW-User » doit contenir un uid de l'utilisateur qui a déclenché l'action d'origine. L'ID utilisateur peut être obtenu à partir du jeton d'accès après une connexion à un service en amont.

Reportez-vous aux documents relatifs à l'autorisation pour en savoir plus sur l'en-tête de demande d'autorisation.

import {
  authTokenHandler,
  HttpRequestBuilder,
  jsonOptions,
} from '@jutro/transport';

export const getRestService = (baseUrl) => {
  const request = new HttpRequestBuilder(baseUrl)
    .addOptions(jsonOptions)
    .addHandler(authTokenHandler);

  const requestService = request.build();
  return requestService;
};

Gestionnaires de remplacement pour accéder à l'en-tête de réponse

Le plan de transport est un mécanisme qui permet de récupérer des données à partir d'un terminal pour les utiliser dans le front-end, et chacun des gestionnaires de ce plan est en fait un crochet qui vous permet d'intercepter le processus de récupération à différentes étapes. onErrorResponse et onException, par exemple, vous permettent de gérer les erreurs qui peuvent se produire dans le cadre du processus de récupération.

Le transport Jutro fournit les gestionnaires suivants :

onAuth : pour gérer l'authentification
onFetch : vous permet de remplacer l'appel de récupération sous-jacent par autre chose
onErrorResponse : pour gérer une réponse d'erreur de service telle qu'une erreur 404 ou 500
onException : pour gérer les exceptions inattendues telles que les erreurs réseau
onResponse : une fois les données extraites, vous utilisez onResponse pour analyser ou effectuer une opération sur ces données.
onTrace : vous permet d'ajouter différents gestionnaires de suivi

Pour accéder aux en-têtes de réponse renvoyés dans une demande, vous pouvez remplacer le comportement par défaut en ajoutant le gestionnaire au HttpRequestBuilder qui est renvoyé après la création de createHttpRequest et l'attribution d'une nouvelle opération à la demande.

Pour ce faire, ajoutez le rappel à la méthode addHandler dans le générateur de requêtes http.

Voici un exemple de la façon dont vous pouvez remplacer les réponses par défaut onResponse et onErrorResponse pour modifier l'objet de l'en-tête de réponse :

import { createHttpRequest } from '@jutro/transport';

...

const responseSuccess = fullResponse => Promise.resolve(fullResponse);

const responseError = fullResponse => Promise.reject(fullResponse);

const pokeService = createHttpRequest('https://pokeapi.co/api/v2/', false) // don't miss the trailing slash
    .addHandler('onResponse', responseSuccess)
    .addHandler('onErrorResponse', responseError)
    .build();

pokeService
    // to get an error response change to 'https://pokeapi.co/api/v2/pokemon/pika'
    .get('pokemon/pikachu', {})
    .then(fullResponse => {
        console.log(fullResponse, 'success');
        console.log(Object.fromEntries(fullResponse.headers), 'success headers');
    })
    .catch(fullResponse => {
        console.log(fullResponse, 'failure');
        console.log(Object.fromEntries(fullResponse.headers), 'failure headers');
    });

Exemples d'objets de réponse de réussite et d'échec

Voici des exemples d'objets de réussite et d'échec de réponse ci-dessus :

Échec de l'objet de réponse

Réussite de l'objet de réponse

Note: Pour accéder à des en-têtes supplémentaires, vous devez configurer CORS.

Envoi de fichiers

Pour envoyer un fichier à partir d'un formulaire HTML (ou d'un objet FormData), il suffit de déposer l'en-tête jsonOptions, fetch ajoutera un en-tête multipart/form-data par lui-même avec une annotation de limite appropriée :

   import { createHttpRequest, authTokenHandler } from '@jutro/transport';

    ...

    restService = createHttpRequest(baseUrl)
        .addHandler(authTokenHandler)
        .build();

utilisez ensuite restService comme suit :

    ...

    const data = new FormData();
    data.append('file_property_name', FILE_OBJECT, 'FILE_NAME');

    restService.post('YOUR_URL', data) //executes your request, use .then() or async/await to handle the response

createJsonHttpRequest

createJsonHttpRequest est une implémentation héritée qui force l'utilisation du application/json Type de contenu. Si vous souhaitez l'utiliser, suivez l'exemple ci-dessous :

   import { createJsonHttpRequest, authTokenHandler } from '@jutro/transport';

    ...

    restService = createJsonHttpRequest(baseUrl, false)
        .addHandler(authTokenHandler)
        .build();

createHttpRequest​

Champ de requête d'autorisation - En-tête HTTP​

Gestionnaires de remplacement pour accéder à l'en-tête de réponse​

Exemples d'objets de réponse de réussite et d'échec​

Envoi de fichiers​

createJsonHttpRequest​

createHttpRequest

Champ de requête d'autorisation - En-tête HTTP

Gestionnaires de remplacement pour accéder à l'en-tête de réponse

Exemples d'objets de réponse de réussite et d'échec

Envoi de fichiers

createJsonHttpRequest