![Presentación
Agrupación de los campos
{
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"address": "D4 JP",
"addressCity": "Lima",
"addressCountry": "Peru"
}
{
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"addressInfo": {
"address": "D4 JP",
"city": "Lima",
"country": "Peru"
}
}
Desagrupado Agrupado](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-17-320.jpg)
![Presentación
Encapsulación de los recursos
No encapsulado Encapsulado
{
"data": {
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"addressInfo": {
"address": "D4 JP ",
"city": "Lima",
"country ": "Peru "
}
}
}
{
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"addressInfo": {
"address": "D4 JP",
"city": "Lima",
"country": "Peru"
}
}](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-18-320.jpg)
![Presentación
Indexación de los recursos
{
"persons/1": {
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"address": "D4 JP",
"addressCity": "Lima",
"addressCountry": "Peru"
}
/* 15 more omitted */
}
[
{
"id": "persons/1",
"userName": "cmamo",
"firstName": "C",
"lastName": "Mamo",
"emails": [
"cmamo@example.com"
],
"address": "D4 JP",
"addressCity": "Lima",
"addressCountry": "Peru"
}
/* 15 more omitted */
]
Indexado No indexado](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-19-320.jpg)
![Presentación
Enlazamiento de recursos
{
"id": 1,
"href": "/posts/1",
"title": "C",
"description": "Mamo",
"comments": [
{
"id": "403",
"href": "/posts/1/comments/403",
"comment": "huehue"
}
/* 175 more omitted */
]
}
Hacia los hijos Hacia el padre
{
"id": 1,
"href": "/posts/1",
"title": "C",
"description": "Mamo",
"comments": {
"count": 176,
"href": "/posts/1/comments/"
}
}](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-20-320.jpg)
![{
"data": {
"id": 1,
"href": "/api/posts/1",
"title": "C",
"description": "Mamo",
"comments": {
"count": 176,
"href": "/api/posts/1/comments/"
}
},
"embedded": {
"comments": [
{
"id": "403",
"href": "/api/posts/1/comments/403",
"comment": "huehue"
/* ... */
}
/* 175 more omitted */
]
}
}
Presentación
Recursos anidados/embebidos
{
"id": “1",
"href": "/api/posts/1",
"title": "C",
"description": "Mamo",
"comments": [
{
"id": "403",
"href": "/api/posts/1/comments/403",
"comment": "huehue",
"count": {
"downvote": 2,
"upvote": 5
}
/* ... */
}
/* 175 more omitted */
]
}
Recursivo Top level / aplanado](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-21-320.jpg)
![Querying
• Las funcionalidades hacen uso del queryString
• Se puede combinar las capacidades
• /items?price=100&sort=name &page=3
Capacidad Ejemplo
Filtrado /items?price[gte]=10&price[lte]=10
Búsqueda /items?q=noodles soup
Paginación /items?page=3&page-size=25
Recursos embebidos /items?fields=brand.name
Ordenamiento /items?sort=price](https://image.slidesharecdn.com/pragmaticrestfulapi-200509164421/85/Fundamentos-para-el-diseno-de-una-RESTful-API-pragmatica-22-320.jpg)
Fundamentos para el diseño de una RESTful API pragmática
- 1. Fundamentos para el diseño de una RESTful API pragmática Leo Wong Febrero de 2020
- 2. Objetivo Obtener el criterio mínimo para el diseño de una RESTful API Conceptos base REST RESTful RESTful pragmático Aspectos técnicos CRUD+L Presentación Permisos Querying Más allá del CRUD+L Manejo de excepciones Fundamentos de diseño Elaboración del diseño Pautas para el diseño Estándares Errores frecuentes
- 4. ¿Qué es REST? • Cuando se piensa en REST se nos viene a la cabeza un Web Service especializado para el CRUD+L • GET /items/{id} • POST /items • PUT /items/1 • DELETE /items/1 • Esta concepción no es del todo correcta
- 5. Entonces, ¿qué REST? • Representational State Transfer • No es una arquitectura • Es un estilo de arquitectura para sistemas distribuidos de hipermedia • Es un conjunto de 6 restricciones/principios usado para crear web services (uso de HTTP). • Fue creado por Roy Fielding en 2000 en su tesis doctoral
- 6. Conceptos relacionados Concepto Definición RESTFul Es una arquitectura que cumple con TODOS los principios REST. Coloquialmente llamado REST Hipermedia Uso de enlaces web Recurso Es una pieza de información de un objeto. Puede tener múltiples representaciones. Colección Varios recursos
- 7. Principios de REST 1. Cliente servidor 2. Sin estado 3. Cacheable 4. Sistema por niveles 5. Interfaz uniforme 1. Identificación basada en recursos 2. Manipulación de recursos a través de representaciones 3. Mensajes autodescriptivos 4. HATEOAS 6. Código bajo demanda (opcional) Separación de responsabilidades Las peticiones no dependen del estado de las anteriores Incluir la suficiente información Una URI por cada recurso Tanto el cliente como el servidor se comunican a través de representaciones Principal forma de optimización Limitación de responsabilidades Hipermedia como motor del estado de la aplicación Extender las capacidades
- 8. RESTful API Pragmática • Pragmático • Que resuelve problemas de una manera práctica y sensata más que tener ideas o teorías fijas • Lo práctico por encima de lo teórico • Existen distintos estilos de diseño para una arquitectura RESTful
- 9. RESTful API Pragmática • ¿Cuándo una API es práctica? • Cumple con sus objetivos con facilidad • Es factible • Es realista • Es versátil • ¿Cuándo una API es buena? • Fácil de aprender • Fácil de usar • Difícil de usarlo mal • Fácil de leer y mantener el código • Fácil de extender • Apropiado para la audiencia Perspectiva del Cliente vs Perspectiva del Servidor
- 10. “La gloria de REST”
- 12. El CRUD+L genérico • Varios métodos en las URL /recursos y /recursos/{id} • Representaciones del cliente vs representación del servidor • Código de estado HTTP manda • Las respuestas del servidor debe dependen del código de estado • El servidor solo puede responder ciertos códigos de estado para cada método HTTP • Es posible hacer operaciones BULK para PUT, PATCH, UPDATE • El comportamiento debe ser consistente para todos los recursos
- 13. CRUD+L MÉTODO HAPPY PATH RESP. HEADER List GET /recursos Cliente: Hace una petición sin cuerpo Servidor: Devuelve una lista de recursos Status-Code: 200 Content-Type Cache-Control Retrieve GET /recursos/1 Cliente: Hace una petición sin cuerpo Servidor: Devuelve un recurso Status-Code: 200 Content-Type Cache-Control Create POST /recursos Cliente: Envía un recurso en representación de creación Servidor: Devuelve el recurso Status-Code: 201 Content-Type Location Update PUT /recursos/1 Cliente: Envía un recurso Servidor: Devuelve el recurso Status-Code: 200 Content-Type Partial Update PATCH /recursos/1 Cliente: Envía un solo unos campos del recurso Servidor: Devuelve el recurso Status-Code: 200 Content-Type Delete DELETE /recursos/1 Cliente: Hace la petición sin cuerpo Servidor: Envía una respuesta sin cuerpo Status-Code: 204
- 14. Permisos 1. https://fb.com/api/posts 2. https://fb.com/api/users/self/posts 3. https://fb.com/api/posts?user=1 • ¿Qué trae? • ¿Todos los post? • ¿Solo los post que el usuario X tiene permitido ver? • Caso de usuario con múltiples roles • ¿Solo los post del usuario X? • ¿Qué hay dentro? • ¿Todo los campos? • ¿Solo los campos que el usuario tenga permisos de ver? HTTP HEADER Vary: Authorization 1 1 2 3 1+3 2+3 1 2 Por permiso Todo o 403 3 Por el usuario especificado QueryString view-as
- 15. Ubicación 1. https://fb.com/api/comments?post=1 2. https://fb.com/api/users/self/comments?post=1 3. https://fb.com/api/users/self/post/1/comments 4. https://fb.com/api/post/1/comments 5. Dentro de https://fb.com/api/post/1 • ¿Dónde los trae? • ¿En todos lados? • ¿Solo en algunos? • ¿Estandarizar uno? Recursos anidados • Relaciones entre recursos • Múltiples relaciones • Posible redundancia • No hacer redireccionamiento • Intentar mantener máximo 2 niveles • En el top level • En las relaciones con otros recursos
- 16. Presentación 1. https://fb.com/api/posts 2. https://fb.com/api/posts/1 • ¿Cómo los trae? • ¿Una de las opciones posee más detalle que el otro? • ¿Cómo se manejan las relaciones? • ¿Cómo están agrupados los datos?
- 17. Presentación Agrupación de los campos { "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "address": "D4 JP", "addressCity": "Lima", "addressCountry": "Peru" } { "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "addressInfo": { "address": "D4 JP", "city": "Lima", "country": "Peru" } } Desagrupado Agrupado
- 18. Presentación Encapsulación de los recursos No encapsulado Encapsulado { "data": { "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "addressInfo": { "address": "D4 JP ", "city": "Lima", "country ": "Peru " } } } { "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "addressInfo": { "address": "D4 JP", "city": "Lima", "country": "Peru" } }
- 19. Presentación Indexación de los recursos { "persons/1": { "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "address": "D4 JP", "addressCity": "Lima", "addressCountry": "Peru" } /* 15 more omitted */ } [ { "id": "persons/1", "userName": "cmamo", "firstName": "C", "lastName": "Mamo", "emails": [ "cmamo@example.com" ], "address": "D4 JP", "addressCity": "Lima", "addressCountry": "Peru" } /* 15 more omitted */ ] Indexado No indexado
- 20. Presentación Enlazamiento de recursos { "id": 1, "href": "/posts/1", "title": "C", "description": "Mamo", "comments": [ { "id": "403", "href": "/posts/1/comments/403", "comment": "huehue" } /* 175 more omitted */ ] } Hacia los hijos Hacia el padre { "id": 1, "href": "/posts/1", "title": "C", "description": "Mamo", "comments": { "count": 176, "href": "/posts/1/comments/" } }
- 21. { "data": { "id": 1, "href": "/api/posts/1", "title": "C", "description": "Mamo", "comments": { "count": 176, "href": "/api/posts/1/comments/" } }, "embedded": { "comments": [ { "id": "403", "href": "/api/posts/1/comments/403", "comment": "huehue" /* ... */ } /* 175 more omitted */ ] } } Presentación Recursos anidados/embebidos { "id": “1", "href": "/api/posts/1", "title": "C", "description": "Mamo", "comments": [ { "id": "403", "href": "/api/posts/1/comments/403", "comment": "huehue", "count": { "downvote": 2, "upvote": 5 } /* ... */ } /* 175 more omitted */ ] } Recursivo Top level / aplanado
- 22. Querying • Las funcionalidades hacen uso del queryString • Se puede combinar las capacidades • /items?price=100&sort=name &page=3 Capacidad Ejemplo Filtrado /items?price[gte]=10&price[lte]=10 Búsqueda /items?q=noodles soup Paginación /items?page=3&page-size=25 Recursos embebidos /items?fields=brand.name Ordenamiento /items?sort=price
- 23. Más allá del CRUD+L • Extensión de la URL del recurso vs RPC • Ejemplos • POST /orders/bulk • GET /orders/report/download • GET /monetary-amount?quantity=100&unit=EUR&in=PEN • Las posibilidades son infinitas • Es la última opción
- 24. Manejo de excepciones • Mensajes de advertencia vs excepción • Representación genérica • Validación • Detalle por cada campo • Mensaje de error en general • Internacionalización • Mensaje de descripción • No se necesario un código de error interno por cada error • Utilizar el código de estado HTTP adecuado • Debugging & Logging
- 26. ¿Por qué diseñar? • Enfoques de desarrollo • Primero el diseño: Contrato Cliente / Servidor • Primero el código: ¿Cómo mantener la consistencia? • Es una API y es un servicio • Es software • Una API solo es tan buna como su documentación • Puede sirve para un cliente, pero ¿servirá para todos?
- 27. Diseño • Actividades en el diseño • Identificación de recursos • Definición de los recursos • Identificación de las relaciones entre los recursos y alcance • Selección de un formato • Definición de las capacidades de las URL • Definición de las representaciones y métodos • Definición del catálogo de la API • Documentación • Entre otros… • ¿Qué tan detallado debe ser el diseño? • ¿Cuánto alcance debe tener el diseño principal? Se parece al diseño de un DB schema
- 28. Pautas para el diseño • Colaboración entre cliente / servidor • Consistencia: seguir un estándar • Debe ser práctico • Debe ser flexible • Debe ser robusto • No se debe exponer la BD como tal • Buena documentación
- 29. Consideraciones técnicas de un API • Versionamiento • Internacionalización • Formato • Datos • Metadatos • Happy path • Capacidades customizadas • Reportería & Analítica • Notificaciones • Manejo de archivos • Querying • Recursos anidados • Infraestructura • Manejo de excepciones • Validaciones • Debugging & Logging • Optimización • Caché • Comprensión • Rate limiting • Latencia • Seguridad • Autenticación • Autorización • Cifrado • CORS • Documentación • Entre otros…
- 30. Estandarización • Formatos • Define un modo de presentación de los recursos en común • Ejemplos: HAL, Siren, Collection+JSON • Esquema • Proporcionan un contexto que brinda significado o definición • Legible por máquinas y humanos • Ejemplos: JSON-SCHEMA, JSON-LD • Especificaciones • Proporcionan restricciones para un alineamiento fuerte en el diseño • Basado en las buenas prácticas • Ejemplos: JSON:API, ODATA • Frameworks • Herramienta que facilita y estructura la implementación • Ejemplos: django-rest-framework, Spring HATEOAS • Documentación • Define el uso de la API • Ejemplo: OpenAPI / Swagger
- 31. Errores frecuentes ¿Qué no tiene sentido hacer? ¿Qué no es práctico? • APIs que solo exponen las tablas de la BD como tal • No importa que tan mal normalizada está la BD • http://www.example.com/api/rest/v4.7.2/en/Module/Controller/People/ • Mal manejo de errores • Mal uso de código de estado • Advertencias en excepciones • Mala descripción de errores • API inconsistentes • Mal versionamiento • Malos nombres • Arquitectura spaghetti
- 33. Resumen y conclusiones • REST = Restricciones • RESTful teórico vs RESTful pragmático • Existen diversas formas de implementación • Pautas en el diseño: • Primero pensar en el diseño, luego en la implementación • API buena y práctica • Consistencia = Seguir un estándar • La práctica hace al maestro
Notas del editor
- #3: El único objetivo de esta presentación va a ser obtener un criterio mínimo para el diseño de una RESTful API. Para aquello vamos a aprender 3 cosas: Algunos conceptos base relacionados a REST; Los aspectos técnicos principales: Esto nos permitirá tener una visión más profunda de cómo funciona los engranajes; y Fundamentos de diseño: Lo propio de esta presentación
- #4: ¿Quiénes de ustedes han utilizado REST? ¿Cuánto tiempo lo han estado utilizando?
- #5: Cuando se piensa en REST, se piensa en un web service especializado en el CRUD. Pero esta concepción no es del todo cierta
- #6: Entonces, ¿qué es REST? REST de Representational State Transfer no es una arquitectura, sino un estilo de arquitectura. Por lo que, se posiciona en un nivel de abstracción más alto que las arquitecturas. Es decir, mediante sus 6 restricciones se puede diseñar distintas arquitecturas. Este concepto fue introducido por Roy Fielding en el año 2000 mientras que trabajaba en conjunto con las especificaciones HTTP. Por lo que, el objetivo de REST es hacer un mejor uso de HTTP.
- #7: Otros conceptos: código de estado HTTP
- #8: Otros conceptos: idempotencia, método seguro, singleton.
- #9: Cliente servidor: Es la separación de responsabilidades entre el cliente y el servidor. Quién se encarga de la GUI y del almacenamiento. De esta manera es escalable para múltiples clientes. Por ejemplo, el cliente es quien hace las peticiones y el servidor las responde. Si el cliente pide que se almacene información relacionada a la GUI se estaría rompiendo este principio. Sin estado: El servidor no debe almacenar nada de la última petición HTTP, pues no debe tener nada de contexto para procesar las peticiones. Esto facilita que haya un proxy. Nada de cookies, sesiones, contexto, etc. Por ejemplo, no se debe dar la posibilidad se configurar un tamaño de página por defecto para futuras peticiones. Cacheable: Uso de cache. Permite mejorar el rendimiento y aligerar el consumo de datos. Sistema por niveles (capas): Permite la separación lógica/física del sistema por capas. Esto aumenta la escalabilidad; una capa solo puede ver las capas a su alrededos. Por ejemplo, un nivel de autenticación, otro almacenamiento de datos y otro de la API. Interfaz Uniforme: es un conjunto de subrestricciones basadas en la URI Identificación basada en recursos: Una URI es la puerta de acceso a los recursos. Se tiene una genérica por cada recurso. Manipulación de recursos a través de representaciones: Recordemos que un recurso tiene varias representaciones. Utilizan estas para comunicarse. Mensajes autodescriptivos: El servidor debe dar la información suficiente para que el cliente la pueda procesar. Ejm, content-type HATEOAS: Según Roy Fielding, HATEOAS es la principal restricción que distingue de una arquitectura RESTful de otras APIs. Esta restricción previene el harcodeo mediante el enlace de recursos desde la raíz. El cliente tendría la capacidad de descubrir y utilizar la API automáticamente. Código bajo demanda: El servidor puede retornar código ejecutable y a veces violar una o dos restricciones.
- #10: A los principios, la implementación de una arquitectura RESTful resultó ser muy difícil de implementar dado a la carencia de herramientas para HATEOAS. Además, en ciertos casos puede no aportar un valor significante para el esfuerzo dado. A las personas que se enfocan en cumplir todas las restricciones REST se las conoce como RESTafarian. Actualmente existen suficientes herramientas para poder implementar HATEOAS sin problemas.
- #12: La migración de APIs no REST (SOAP) a REST conlleva una serie de etapas. El modelo de maduridad de Richardson provee niveles y objetivos a alcanzar.
- #15: Este es el uso más común del CRUD+L en una RESTful API. En ciertos recursos puede que se requiera utilizar otro código de estado HTTP, por la respuesta del servidor puede variar.
- #16: Existen varias formas de la implementación de permisos. La más utilizada es el filtrado de datos por permiso en el listado (cabecera Vary: Authorization).
- #17: Los recursos anidados proveen relaciones entre recursos mediante el uso de la URL. Puede haber más de una relación en un recurso anidado. Por ejemplo, /user/self/posts puede traer los posts creados por el usuario o los posts a mostrar al usuario. Normalmente se utiliza la relación más explícita.
- #18: Considerar consistencia para el detalle (se puede utilizar elementos embebidos mediante el queryString).
- #19: El estilo desagrupado no correlaciona los datos. Mientras que el agrupado, los correlaciona y agrupa en un campo. Aunque ciertos datos puedan estar correlacionados, pueden no agruparse según cierto criterio.
- #20: El estilo no encapsulado muestra la data directamente. Mientras que, el estilo encapsulado, agrupa la data en un campo. La encapsulación puede mejorar la manipulación de las representaciones y su extensión.
- #22: El enlazamiento de datos hacia los hijos puede consumir una gran cantidad de ancho de banda cuando se utiliza en listados. La dirección padre (example.com/api) enlaza a los recursos de primer nivel.
- #23: El estilo recursivo permite el acceso directo a los datos por si agrupación inmediata. Sin embargo puede contener redundancia de datos cuando pasa de 2 niveles. Por otro lado, el estilo top level o aplanado requerirá lógica adicional para interactuar con los datos anidados; pero estos no tendrán redundancia.
- #24: El queryString es la sección de la URL que va después del signo de interrogación (?). En esta sección se permite pasar parámetros. Dado aquello, tenemos ciertas funcionalidades de la API que ayudan a la manipulación de datos. Existen diversos diseños (ver anexos queryString).
- #25: Remote Procedure Call
- #28: DX Developer Experience: Ponerse en los zapatos de los clientes UX -> APX (Application Programming Experience) Buenas practicas de programación Patrón fachada: ocultar la lógica abrumadora y proporcionar una interfaz for dummies Nombres con sentido Sin side effects
- #29: El diseño es la etapa del ciclo de vida de software que va después de la captura y análisis de requerimientos. El diseño de una API RESTful comprende varias actividades que son plasmadas en un documento. Algunas de estas actividades que corresponden a un nivel más alto de abstracción como la selección de un formato pueden ser estandarizadas por la empresa. Esto es para mantener la consistencia en múltiples microservicios. Existen metodologías específicas para el diseño de la API incluso ciclos de vida específicos. Pero es software, se puede utilizar las metodologías de desarrollo. Claro que como es una API se tiene que ser más cauteloso. ¿Cuándo la API se rompe? Cuando se cambia de nombre Cuando se eliminan o cambian funcionalidades o campos ¿Cuándo no se rompe? Añadir campos Añadir recursos
- #30: Realizar el contrato de la API no significa que se deba utilizar la metodología en cascada. Se recomienda utilizar las metodologías ágiles para el diseño del contrato siempre que se pueda.
- #32: Formato Existen distintos formatos dado a los estilos de presentación que se mencionaron Esquema Significado: Proporciona un vocabulario común y el contexto estandarizado para el tipo del objeto. Mediante esto la máquina es capaz de reconocer los atributos de un recurso. Por ejemplo, persona: nombre, apellido, etc. En este caso se utiliza el estándar JSON-LD que aporta un formato especial y enlace a datos. Dada esta capacidad, la máquina será capaz de realizar búsquedas automatizadas en los recursos enlazados. Definición: Proporciona una estructura bien definida que ayuda en las validaciones. Mediante esto la máquina es capaz realizar validación automática a los objetos JSON; qué campos son obligatorios y qué campos no. En este caso se utiliza el estándar JSON-SCHEMA que aporta funcionalidades de documentación y validación. Dada esta capacidad, se poseerá validación desde el cliente y documentación automática. Especificaciones Estas especificaciones han predefinido el diseño de varias especificaciones técnicas. Por ejemplo, ¿qué formato utilizar? ¿qué diseño de querying utilizar? Documentación El estándar OpenAPI provee un lenguaje para descubrir las capacidades de la API dado personas y máquinas