Saltar al contenido principal

Capa de transporte para servicios REST

En este tema se explica cómo crear un servicio REST con la capa @jutro/transport para enviar y recibir solicitudes HTTP.

El transporte de Jutro contiene las siguientes opciones a la hora de enviar y recibir solicitudes.

  • HttpRequestBuilder: Encapsulador extensible alrededor de 'fetch' para realizar llamadas REST. Proporciona una matriz de resoluciones de 'option' para inyectar opciones y encabezados en la solicitud. También le proporciona codificadores/decodificadores para transformar los datos enviados y los recibidos, y proporciona devoluciones de llamada para monitorear el flujo solicitud > respuesta > excepción.
  • createHttpRequest: Crea la solicitud http usando el HttpRequestBuilder.
  • createJsonHttpRequest: Crea una solicitud http pero especifica el tipo de contenido JSON, para que el servidor sepa en qué formulario deben estar los datos que envía.
  • basicAuthOptions: Se utiliza para pasar un nombre de usuario y una contraseña con autenticación básica en una llamada REST; en cambio, recomendamos encarecidamente utilizar authTokenHandler con autenticación de Jutro.
  • jsonOptions: Proporciona un encabezado JSON para solicitudes con carga útil JSON.
  • langLocaleOptions: Proporciona encabezados gw-language y gw-locale para las solicitudes.
  • analyticsHandler: Controla el pasaje de una carga útil de evento en la solicitud http a un eventTopicMap para que pueda enviarse a un motor de análisis.
  • authTokenHandler: Crea opciones de autenticación mediante un token de portador de autenticación de Jutro para pasar a HttpRequestBuilder.
  • zipkinTraceHandler: Proporciona una extensión de opciones de seguimiento.

createHttpRequest​

Para crear una solicitud http como servicio REST:

  1. Importe createHttpRequest desde @jutro/transport:

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

  2. Cree una variable como la restService que aparece a continuación:

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

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

  3. Cree una función que ejecute la solicitud:

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

Puede pasar opciones como el último argumento de funciones como get() o post().

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

Para pasar encabezados personalizados a su solicitud, use .addOptions siguiente manera:

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

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

Campo de solicitud de autorización: encabezado HTTP​

Puede agregar un encabezado de autorización en el servicio REST mediante authTokenHandler con las funciones get() o post(), o bien, con el método addHandler().

En la implementación predeterminada, authTokenHandler obtiene el token de autenticación y agrega también el encabezado Authorization, junto con 'GW-Tenant' y 'GW-User', según los datos almacenados en el token.

Para cada llamada a la API que cree o modifique un conjunto de trabajo, recurso o inquilino, la solicitud deberá contener el ID de usuario 'GW-User', uid.

Las siguientes son reglas generales cuando se usa 'GW-User' como parte de una llamada a la API:

  1. Si la llamada a la API utiliza un token de acceso de usuario para autorizar, el encabezado 'GW-User' debe ser igual a una notificación uid en ese token. Las llamadas se rechazarán si no hay coincidencia entre el encabezado y el token.
  2. Si la llamada a la API utiliza un token de acceso de servicio para autorizar, el encabezado 'GW-User' debe contener un uid del usuario que inició la acción original. El ID de usuario se puede obtener del token de acceso después de iniciar sesión en un servicio anterior.

Consulte los documentos sobre Autorización para obtener más información sobre el encabezado de la solicitud de autorización.

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;
};

Invalidación de controladores para acceder al encabezado de respuesta​

La capa de transporte es un mecanismo para recuperar datos desde un terminal para que el frontend los consuma, y cada uno de los controladores dentro de esa capa son, en efecto, ganchos que le permiten interceptar el proceso de recuperación en diferentes etapas. onErrorResponse y onException, por ejemplo, le brindan la capacidad de administrar los errores que puedan ocurrir como parte del proceso de recuperación.

El transporte de Jutro proporciona los siguientes controladores:

  • onAuth para manejar la autenticación.
  • onFetch le permite cambiar la llamada de recuperación subyacente por otra cosa.
  • onErrorResponse para ocuparse de una respuesta de error de servicio, como un error 404 o 500.
  • onException para administrar excepciones inesperadas, como errores de red.
  • onResponse, una vez que se hayan recuperado los datos, utilice onResponse para analizar o realizar una operación con esos datos.
  • onTrace le permite agregar diferentes controladores de seguimiento.

Para acceder a los encabezados de respuesta devueltos en una solicitud, puede invalidar el comportamiento predeterminado agregando el controlador al HttpRequestBuilder que se devuelve después de crear createHttpRequest y asignar una nueva operación a la solicitud.

Para ello, agregue la devolución de llamada al método addHandler en el generador de solicitudes http.

A continuación, se muestra un ejemplo de cómo invalidar el valor onResponse predeterminado y la respuesta onErrorResponse para modificar el objeto de encabezado de respuesta:


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');
    });

Ejemplos de objetos de respuesta correctos y fallidos​

A continuación, se muestran ejemplos de los objetos de respuesta correctos y fallidos anteriores:

Objeto de respuesta fallido Objeto de respuesta fallido

Objeto de respuesta correcto Objeto de respuesta correcto

Note: Para acceder a encabezados adicionales, deberá configurar CORS.

Envío de archivos​

Para enviar un archivo desde un formulario HTML (u objeto FormData) simplemente suelte el encabezado jsonOptions. fetch añadirá un encabezado multipart/form-data por sí mismo con una anotación de límite adecuada:

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

    ...

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

Luego, use restService de esta manera:

    ...

    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 es una implementación heredada que fuerza el uso de application/json tipo de contenido. Si desea utilizarla, siga este ejemplo:

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

    ...

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