Diseño de servicios web de tipo REST.
Diseño de API y servicios web RESTful
El enfoque principal del diseño de servicios web RESTful es identificar los activos z/OS que se deben ofrecer, determinar los métodos HTTP a los que desea que estos activos proporcionen soporte y, a continuación, correlacionar los identificadores de recursos y métodos con dichos activos.
Los métodos definidos por la especificación HTTP proporcionan una interfaz uniforme para interactuar con los recursos de la web. Todos los navegadores web, servidores y aplicaciones entienden esta interfaz uniforme y la semántica de cada operación. Pueden conectarse entre sí e intercambiar información utilizando esta interfaz uniforme, independientemente de las diferencias en las plataformas o la tecnología.
Después de que se determinen los recursos que deben presentarse al servicio, el siguiente paso es diseñar una API REST. Esta API es la interfaz de usuario para los consumidores de la API. Los consumidores de la API pueden ser desarrolladores de aplicación que necesitan crear clientes RESTful para acceder a los servicios, o bien un desarrollador de integración que publica las API en IBM® API Connect.
Una API REST describe un conjunto de recursos y un conjunto de métodos a los que se puede llamar para actuar sobre esos recursos. Los métodos de una API REST se pueden llamar desde cualquier cliente HTTP, incluido el código JavaScript del lado del cliente que se ejecuta en un navegador web. La API REST tiene una vía de acceso base, que es similar a una raíz de contexto. Todos los recursos de una API REST se definen de forma relativa a su vía de acceso base. La vía de acceso base se puede utilizar para proporcionar un aislamiento entre las distintas API REST. El cliente HTTP utiliza una vía de acceso relativa a la vía de acceso base que identifica el recurso de la API REST al que accede el cliente. Las vías de acceso a un recurso pueden ser jerárquicas y una estructura de vías de acceso bien diseñada puede ayudar al consumidor de la API REST a entender los recursos que están disponibles en la API REST. En la tabla siguiente se indican algunos recursos de ejemplo para una base de datos de pacientes en la API REST:
Tabla 1. Recursos de ejemploRecurso
Descripción
/patientsTodos los pacientes de la base de datos/patients/12345Patient #12345/patients/12345/ordersTodos los números de prescripción para el paciente #12345/patients/12345/orders/67890Prescripción número 67890 para el paciente número 12345
Cada recurso de la API REST tiene un conjunto de métodos a los que puede llamar un cliente HTTP. En la tabla siguiente se indican métodos de ejemplo para el recurso /patients/12345:
Tabla 2. Operaciones de ejemploMétodo HTTP
Descripción
GETRecuperar los detalles del paciente de la base de datos.PUTActualizar los detalles del paciente en la base de datos.DELETESuprimir el paciente de la base de datos.
Para actualizar la información de dicho paciente, el cliente HTTP debe realizar una solicitud PUT de HTTP para /patients/12345.
Con una interfaz uniforme para la comunicación, los desarrolladores de aplicaciones pueden centrarse en los recursos en lugar de los métodos. Pueden crear sus aplicaciones sin tener que lidiar con un sistema complejo ni aprender los entresijos de nuevas interfaces. También pueden cambiar libremente sus aplicaciones mientras que los métodos de comunicación que conectan con estos recursos permanecen estables.
Cada combinación de vía de acceso y método de una API REST puede tener también un conjunto de parámetros que el cliente HTTP puede utilizar para pasar argumentos. Cada parámetro debe estar definido en las definiciones de la API REST. Cada parámetro tiene un tipo y un nombre exclusivo. Se admiten varios tipos de parámetros en las API REST en z/OS Connect EE:
Recomendado por LinkedIn
Parámetros de vía de acceso
Se pueden utilizar para identificar un recurso concreto. El cliente HTTP pasa el valor del parámetro como una parte variable del URL y el valor del parámetro se extrae de la vía de acceso para su uso en la operación. Los parámetros de vía de acceso se denotan utilizando la sintaxis {paramName} en la vía de acceso al recurso. Por ejemplo, el ID de paciente se puede pasar como un parámetro de vía de acceso denominado patientID:
/patients/{patientID}
Parámetros de consulta
El cliente HTTP pasa el valor de un parámetro de consulta como un par clave-valor en la serie de consulta al final del URL. Como ejemplo, los parámetros de consulta se pueden utilizar para pasar un número mínimo y un número máximo de resultados a devolver por una llamada determinada:
/patients?min=5&max=20
Parámetros de cabecera
El cliente HTTP puede pasar parámetros de cabecera añadiéndolos como cabeceras HTTP en la solicitud HTTP. Como ejemplo, se puede utilizar un parámetro de cabecera para pasar un identificador exclusivo que identifica el cliente HTTP que llama a la API:
Api-Client-Id: fffe2c5d-42d5-7428-5f5f-abc34ab7f555
Para ofrecerle ayuda en el diseño y el desarrollo de esta API, z/OS Connect EE proporciona un editor gráfico, el kit de herramientas de API de z/OS Connect EE.
Diseño de API para su uso con interceptores
Los interceptores de servicio no se llaman para solicitudes de API. Los interceptores que se han configurado para los servicios solo se desencadenan si el servicio se invoca directamente desde una solicitud HTTP o HTTPS. No se desencadenan si el servicio se invoca desde una API.
Tenga en cuenta los criterios siguientes cuando diseñe las API para trabajar con interceptores:
RESUMEN