En el último artículo de esta serie, aprenderá sobre las recomendaciones de API REST y ejemplos de desarrollo de Java y Spring Web Services.
Al desarrollar una buena API REST, es importante tener buenos microservicios.
¿Cómo desarrollas tu API REST? ¿Cuáles son las mejores prácticas?
Aprenderás:
- ¿Cómo desarrollar una buena API REST?
- ¿En qué debo pensar al desarrollar una API REST?
- ¿Cuáles son las mejores prácticas para desarrollar servicios web RESTful?
API REST
Este es el último artículo de una serie de artículos sobre la API REST:
Utilice el primer enfoque del consumidor
¿Quién usará su servicio? Servicios al consumidor.
¿Miras el servicio desde la perspectiva del consumidor?
- Si está desarrollando una API, ¿puede su consumidor comprender su API?
- Si publica sus recursos, ¿puede el consumidor encontrarlos y acceder a ellos?
- ¿Puede el consumidor entender sus URI?
- ¿Qué tipo de servicio brindan?
- ¿Es esta una aplicación móvil o una aplicación web?
- ¿Qué consumidores espera, y pueden estos tipos de consumidores cambiar en el futuro?
- Si está implementando algo como HATEOAS, piense en cómo lo usarán sus clientes antes de implementarlo.
- Lo más importante es tener una excelente documentación.
- Facilite las cosas a sus clientes para ahorrarle tiempo.
- Cuantos más consumidores puedan hacer solos, menos trabajo tendrá para usted.
Siempre que tenga una discusión o revisión de servicio, ponga los requisitos del cliente en primer lugar.
Utilice el primer enfoque del contrato
¿Qué es un contrato?
El creador del servicio web se considera
un proveedor de servicios . Una aplicación que utiliza un servicio web es un
consumidor del servicio .
Un contrato es un acuerdo entre un proveedor y un consumidor sobre un servicio.
Para utilizar el servicio correctamente, el consumidor del servicio debe comprender completamente el contrato. El contrato incluye detalles de muchos aspectos del servicio, tales como:
- ¿Cómo llamar a un servicio web?
- ¿Qué tipo de transporte se utiliza?
- ¿Cuáles son las estructuras de solicitud y respuesta?
Esto también se llama
definición de servicio .
En el primer enfoque del contrato, primero define un contrato de servicio y luego solo implementa el servicio.
Contrato primero con WSDL
Por ejemplo, cuando define servicios web SOAP, utiliza WSDL para definir el contrato.
El WSDL determina cuáles son los puntos finales del servicio, las operaciones que publica y las estructuras de solicitud y respuesta.
Contrato primero con Swagger / API abierta
Cuando utiliza los servicios web RESTful, Swagger es una herramienta popular para documentar sus servicios web.
Swagger le permite determinar qué recursos proporciona como parte de su API. Incluye los detalles de cada operación, por ejemplo, si utiliza XML, JSON o ambos. Un esquema de respuesta también está allí.
También proporciona información detallada sobre los códigos de respuesta que admite. También puede ver que este recurso en particular,
/ jpa / users :
Admite la operación GET. De hecho, también es compatible con la operación POST:
El esquema de respuesta, si este recurso está disponible, será:
La definición del objeto Usuario está presente en el acuerdo Swagger como:
Incluye atributos:
birthDate ,
id ,
name y una variedad de mensajes
publicados . Algunos campos también incluyen un campo de descripción dentro de ellos.
En el primer enfoque del contrato, antes de implementar el servicio, usted manualmente o usando la aplicación crea la definición que creó Swagger.
Beneficios del contrato Primer enfoque
Usando el primer enfoque del contrato, piensa en sus clientes y cómo pueden usar este servicio. Inicialmente no le preocupan los detalles de implementación.
Si en la etapa inicial le da gran importancia a la implementación, los detalles técnicos penetran en la definición de su servicio.
Debe asegurarse de que la definición de su servicio no dependa de la plataforma que esté utilizando, ya sea Java, .NET o cualquier otra.
Definir estándares de organización para la API REST
Una directriz importante para sus estándares organizacionales es YARAS.
YARAS significa
Yet Another RESTful API Standard . YARAS proporciona los estándares, pautas y convenciones que deben seguirse al desarrollar servicios web RESTful. Él da recomendaciones para las siguientes cosas:
- ¿Cómo debe nombrar sus servicios?
- Cómo debe estructurar su solicitud y respuesta
- Cómo debe implementar el filtrado, la ordenación, la paginación y otras acciones
- Cómo debe abordar el versionado
- ¿Cómo necesita acercarse a la documentación de la API?
Enfoque unificado para el desarrollo de servicios
Debe resolver muchos problemas complejos antes de comenzar a diseñar servicios web RESTful. Todo lo anterior, debe averiguarlo.
El liderazgo de su organización no querrá que los equipos que manejan diferentes recursos tengan enfoques diferentes para estas cosas.
Por ejemplo, no es deseable que el Equipo A organice el control de versiones basado en parámetros de consulta y que el Equipo B use el control de versiones basado en URI.
Por lo tanto, es importante que haya definido claramente los estándares organizacionales para su enfoque de los servicios web RESTful.
Personalización de YARAS BAJO necesidades organizacionales
Lo bueno de YARAS es que se puede personalizar para satisfacer las necesidades específicas de la organización. Por ejemplo, puedes:
- Configure el aspecto de los cuerpos de solicitud y respuesta.
- Elija un sistema de control de versiones específico
Dado que YARAS tiene una cobertura bastante completa, puede estar seguro de que no se ha perdido una sola decisión importante.
Elegir un marco empresarial estándar REST API framework
Los marcos típicos utilizados para crear servicios web RESTful en el mundo Java son Spring MVC, Spring REST y JAX-RS.
Si crea una aplicación de marco / arquetipo / referencia específica de la organización que se adhiere a los estándares comunes de la organización además de la plataforma API REST preferida, esto permitirá a los equipos adherirse fácilmente a los estándares comunes.
Las características típicas incluyen:
- Estructuras de solicitud y respuesta
- Manejo de errores
- filtrado
- Buscar
- Versionado
- Soporte de respuesta falsa
- Hateoas
El marco estándar proporciona un enfoque unificado para diseñar e implementar servicios en toda la organización.
Gestión descentralizada de API REST
Cree un grupo de expertos de los equipos que crean la API REST y forme un equipo de administración. El equipo es responsable de
- Mejora de los estándares API REST
- Creación / diseño de su marco API REST
Uso generalizado de HTTP
Siempre que piense en servicios web RESTful, piense en HTTP.
HTTP tiene todas las características que lo ayudan a crear excelentes servicios web.
Utilice los métodos de solicitud HTTP correctos
Piense en los métodos de solicitud HTTP que necesita usar. Cuando piense en implementar una operación, determine el recurso en el que debe realizarse y luego encuentre el método de solicitud HTTP adecuado. ¿Recuperas detalles, creas algo, actualizas algo existente o eliminas uno existente?
Usando métodos HTTP:
- OBTENER para obtener
- Publicar para crear
- PONER para actualizar
- BORRAR para borrar
- PARCHE para actualizaciones parciales
Use el estado de respuesta HTTP apropiado
Al realizar la operación, asegúrese de devolver el estado de respuesta correcto.
Por ejemplo, cuando no se encuentra un recurso específico, no arroje una excepción de servidor. En su lugar, envíe el código de respuesta apropiado en un mensaje de respuesta, como
404 .
Si realmente hay una excepción de servidor, envíe el código
500 de regreso.
Si la validación falla, envíe el código para la solicitud no válida.
Centrarse en el rendimiento
Cada recurso puede tener varias representaciones, en formato XML o JSON. El consumidor del servicio puede elegir la presentación que prefiera.
El servicio devuelve 3 usuarios cuando enviamos una solicitud GET. En este caso, obtenemos la representación JSON del recurso
/ users .
Cuando el consumidor no indica una vista preferida, usamos JSON.
El consumidor puede enviar un encabezado Aceptar para indicar la vista.
El cuerpo de respuesta ahora tiene contenido XML:
Usa el plural
Siempre use el plural cuando nombre los recursos.
Veamos un ejemplo simple. Supongamos que tenemos un servicio que aloja un recurso de usuario. A continuación se describe cómo acceder a ellos:
- Crear usuario: POST / usuarios
- Eliminar usuario: ELIMINAR / usuarios / 1
- Obtenga todos los usuarios: GET / usuarios
- Obtenga un usuario: GET / users / 1
La preferencia de múltiples usuarios sobre el usuario usuario hace que el URI sea más legible.
- Por ejemplo, si usamos / user en lugar de / users para obtener, GET / user no pasa el mensaje correcto al lector.
Crea buena documentación
Los consumidores necesitan entender cómo hacer el mejor uso del servicio, y la mejor manera de ayudarlos es crear una buena documentación.
Los servicios web SOAP pueden usar la funcionalidad WSDL, mientras que los servicios web RESTful tienen opciones Swagger (ahora el estándar de documentación Open API).
Elegir un formato es solo una parte de la creación de buena documentación. Lo que también es importante es proporcionar la cantidad correcta de información para ayudar al consumidor.
La documentación debe estar completa e incluir los siguientes puntos:
- ¿Qué es una estructura de solicitud y respuesta?
- ¿Cómo debe autenticarse un consumidor?
- ¿Cuáles son los límites de uso?
- Indique todos los tipos de mensajes de respuesta y los códigos de estado correspondientes que se pueden esperar del servicio.
Crear un portal de documentación de API REST común
Sería útil tener un portal de documentación REST API común para toda la organización. Eche un vistazo a uno de esos portales:
Dicho portal reúne todos los recursos disponibles en la organización. Tener una interfaz de usuario como la interfaz de usuario Swagger tendrá sus beneficios adicionales. Con la interfaz de usuario de Swagger, puede ver la documentación con más detalle:
Esto puede ser utilizado incluso por usuarios no técnicos. La información proporcionada aquí incluye:
- Formato de respuesta esperado
- Tipo de contenido
- Códigos de respuesta admitidos
El formato de documentación en el estilo de una solicitud / respuesta en vivo también puede ser de interés.
Soporte de la versión
El control de versiones conlleva una gran complejidad para un servicio web. Mantener varias versiones diferentes del mismo servicio web es muy difícil. Intenta evitar esto siempre que sea posible.
Sin embargo, en ciertos escenarios, el control de versiones es inevitable.
Comencemos mirando un ejemplo de servicio. Supongamos que inicialmente definimos un servicio que tiene la clase
PersonV1 de la siguiente manera:
Esta versión de la clase no tiene en cuenta que un nombre puede tener muchas subsecciones, como nombre y apellido. Mira esto:
La segunda versión de la clase fuente se ha actualizado para corregir esta anomalía:
¡No podemos transferir de inmediato todo el servicio para usar
PersonV2 ! Puede haber otros consumidores que estén esperando respuestas en formato
PersonV1 .
Aquí es donde se requiere el control de versiones.
Veamos ahora las opciones que tenemos para el control de versiones de estos dos recursos.
Usando diferentes URI
Tenemos una opción: usar diferentes URI para estos diferentes recursos. En el código del examen a continuación, utilizamos los URI
v1 / persona y
v2 / persona para distinguirlos:
Si ejecuta una solicitud GET para el recurso
v1 / persona :
Recibirá la información correspondiente a
v1 . Para otro recurso:
Usando el parámetro de consulta
El segundo método de control de versión utiliza el parámetro de consulta:
En el URI
/ person / param , si enviamos el parámetro con
version = 1 , devolvemos un recurso de tipo
PersonV1 :
Para el mismo URI, el parámetro con
versión = 2 devuelve un recurso de tipo
PersonV2 :
Este método se llama versionado usando parámetros de consulta.
Usar un encabezado (encabezado)
Otra forma de hacerlo es mediante el control de versiones especificando un título. Aquí usamos un encabezado llamado
X-API-VERSION y marcamos el URI como
/ person / header . Cuando el valor del encabezado es
1 ,
se devuelve un recurso de tipo
PersonV1 :
Cuando su valor es
2 , se recupera un recurso de tipo
PersonV2 :
Usamos el atributo en el encabezado de solicitud para realizar el control de versiones para nosotros.
Usar Aceptar encabezado
El método final para crear versiones utiliza el Encabezado de aceptación. Si el consumidor incluye la información de la primera versión en el Encabezado de aceptación de la solicitud GET, se devuelve el siguiente recurso:
De lo contrario,
se devuelve un recurso de tipo
PersonV2 :
Este método de control de versiones se denomina
Aceptar versiones de encabezado o
Versiones de tipo de medio , ya que los tipos MIME suelen ser el contenido del encabezado Aceptar.
Comparación de métodos de control de versiones
Hasta ahora, hemos visto cuatro tipos de métodos en las versiones:
- Usando diferentes URI
- Usando el parámetro de consulta
- Uso de encabezado
- Uso de aceptar encabezado / tipo de medio
Cual es el mejor? La verdad es que no hay una respuesta única para esta pregunta. El hecho del asunto es que diferentes gigantes de Internet patrocinan diferentes tipos de versiones.
- Uso de diferentes URI - Twitter
- Usar el parámetro de consulta - Amazon
- Usando un encabezado - Microsoft
- Uso de aceptar encabezado / tipo de medio - GitHub
Debe evaluar estas cuatro opciones según sus necesidades específicas. Hay una serie de factores importantes a considerar:
- Contaminación de URI : al controlar las versiones con URI y parámetros de consulta, terminamos contaminando el espacio de URI. Esto se debe a que agregamos prefijos y sufijos a las cadenas principales del URI. El control de versiones usando un encabezado evita esto.
- Uso indebido de los encabezados HTTP . En el caso del control de versiones que usa encabezados y Tipo de medio, los encabezados HTTP se usan incorrectamente porque no estaban destinados originalmente para el control de versiones.
- Almacenamiento en caché : un recurso se identifica por su URI. Sin embargo, si no utiliza un URI para determinar su versión, sino que utiliza un mecanismo basado en encabezado, la información de la versión no se puede almacenar en caché. Si el almacenamiento en caché HTTP es importante para usted, use el control de versiones basado en un URI o parámetro de solicitud.
- Ejecutabilidad de solicitud del navegador : el control de versiones basado en el título y el tipo de medio requiere herramientas como Postman. Sin embargo, si los consumidores de servicios no tienen conocimientos técnicos, es preferible utilizar el control de versiones basado en un URI o parámetro de consulta.
- Documentación de API : también debe pensar cómo desea documentar sus API. El control de versiones basado en el URI y el parámetro de consulta es más fácil de documentar que los otros dos tipos de control de versiones.
¡Comprenda que no existe una solución ideal única!
Piensa en el manejo de errores
Cuando un consumidor envía una solicitud a un servicio, es importante que reciba la respuesta correcta. Cada vez que algo sale mal, es importante enviar una respuesta adecuada.
Cuando un consumidor solicita un recurso inexistente
Si enviamos una solicitud GET para buscar un usuario existente, obtenemos la siguiente respuesta:
Si está buscando un usuario inexistente:
Lo que obtienes es el estado
404 No encontrado . Este es un buen manejo de errores porque determina correctamente que no se encontró el recurso y no devuelve un error del servidor.
Ahora enviemos una solicitud GET a un URI inexistente:
Como puede ver, obtiene
404 estados de respuesta
No encontrado . Una URL no válida indica un recurso que no existe.
Importantes estados de respuesta
- 200 - éxito
- 404 - recurso no encontrado
- 400 - solicitud no válida (por ejemplo, error de validación)
- 201 - creado
- 401 - no autorizado (si falla la autenticación)
- 500 - error del servidor
Detalles del error en el cuerpo de respuesta
Esto ayuda si tiene una estructura de excepción estándar al desarrollar su servicio.
Para errores específicos, las estructuras de respuesta específicas pueden devolverse al consumidor, y este puede ser el estándar en toda la organización. Asegúrese de que la respuesta de error también sea legible para los consumidores, sin confusión.
Usando Swagger o Open API Documentation
Swagger proporciona uno de los formatos de documentación más populares para los servicios web RESTful. Hoy cuenta con el respaldo de varias organizaciones y se utiliza en una gran cantidad de servicios. Aquí nos fijamos en dos aspectos principales de Swagger:
- Formato de documentación de Swagger
- Swagger UI, que le permite ver la documentación de Swagger de una manera visualmente conveniente
Documentación Swagger
Eche un vistazo al siguiente Swagger JSON:
En el nivel superior, esto se parece mucho a la definición de WSDL. Tiene varios atributos importantes:
- host : donde se encuentra el servicio
- basePath : la ruta donde se encuentra el servicio
- consume : qué solicitudes son aceptadas
- produce : qué tipos de respuestas se generan
- rutas : varios recursos disponibles En este caso, tiene varios tipos de recursos en la lista:
Cuando mira la documentación de Swagger, puede identificar rápidamente los recursos disponibles, las operaciones compatibles y las operaciones relacionadas con cada recurso:
El recurso
/ users admite operaciones
GET y
POST . Para
GET, puede ver los tipos de solicitud y respuesta admitidos. También ve varios tipos de respuestas:
Tenga en cuenta que para la respuesta
200, el circuito también se conoce como una matriz de
usuario .
El usuario es parte de la sección de
definiciones en la parte inferior del documento:
Swagger es completamente independiente de la tecnología que utiliza para implementar un servicio web RESTful. Oh, todo está basado en JSON.
Introduciendo Swagger UI
La interfaz de usuario de Swagger es una excelente interfaz de usuario que es muy útil para visualizar la documentación de Swagger para el servicio web RESTful.
Eche un vistazo a la siguiente captura de pantalla:
tenga en cuenta que hemos seleccionado una versión específica del servicio web para ver su documentación. Aquí está la misma pantalla con más detalle:
cuando vamos a la página de inicio, describe los recursos enumerados:
También puede ver el conjunto de operaciones admitidas para las URL de recursos:
cuando hace clic en la operación GET de un recurso específico, obtiene sus detalles:
Puede ver que el esquema Los modelos se describen visualmente. También se muestran los atributos birthDate , id , enlaces , nombre y publicaciones . También puede ejecutar una consulta de ejemplo y ver la respuesta:
Uso de herramientas Swagger (Open API Standard)
Lo mejor de Swagger son las muchas herramientas disponibles a su alrededor. Eche un vistazo al siguiente servicio que utilizamos anteriormente para explicar el control de versiones: Aquí hay un vistazo a la documentación generada automáticamente para este servicio:
Swagger tiene soporte para el enfoque de primer contrato y el enfoque de primer código.Sobre este tema hay un video del autor .Resumen
En este artículo, analizamos las mejores prácticas para crear y diseñar servicios web RESTful.Lectura adicional
¡Sé el MEJOR en tu API REST!Desarrollando API REST