El libro de Williams Vincent explica desde los conceptos Basicos de las Web APIs y el uso de Django Rest Framework hasta el proceso de documentación de una API.
Los conceptos pueden ser muy básicos si ya se tienen conocimientos previos, por lo que es muy bueno para una persona que apenas esta entrando en el mundo de Python. Sin embargo, aunque ya hayas trabajado con DRF y Django para montar una API, siempre es bueno volver a leer los conceptos básicos, aprendes algo nuevo cada vez.
En mi caso, en esta publicación, quisiera hablar de 3 Capítulos del Libro que creo son muy importantes que sepamos.
Capitulo 2 - Web APIs
La web, tal como la conocemos, descansa sobre una serie de tecnologías, incluidas HTTP y TCP/IP. En este capítulo, se explican los conceptos básicos de las APIs web. como los endpoints, recursos, verbos HTTP, códigos de estado HTTP y REST. Explicare cada elemento de forma muy breve. El libro tiene unas paginas de la historia, que es interesante pero no lo pondré aquí.
URLs: Una URL es la dirección de un recurso en internet. Por ejemplo, la página de inicio de Google está en https://www.google.com. Cada URL tiene potencialmente tres partes: esquema (https), nombre de host (www.google.com) y una ruta opcional (/about/).
Protocolo de Internet: Cuando se ingresa una URL en un navegador, se utiliza un servicio de nombres de dominio (DNS) para traducir el nombre de dominio en una dirección IP. Luego, se establece una conexión TCP para garantizar la comunicación confiable entre el cliente y el servidor.
Verbos HTTP: Las páginas web tienen direcciones (URL) y una lista de acciones aprobadas conocidas como verbos HTTP, que mapean a funcionalidades CRUD (Create, Read, Update, Delete). Las acciones más comunes son POST (crear), GET (leer), PUT (actualizar) y DELETE (eliminar).
Endpoints: En lugar de servir páginas web, una API web produce endpoints que contienen datos, generalmente en formato JSON, y una lista de acciones disponibles (verbos HTTP).
HTTP: Es un protocolo de solicitud-respuesta entre dos computadoras. Cada mensaje HTTP consta de una línea de estado, encabezados y datos opcionales del cuerpo.
Códigos de Estado: Acompañan cada respuesta HTTP e indican si una solicitud fue exitosa, redirigida, si hubo un error del cliente o del servidor.
Statelessness: HTTP es un protocolo sin estado, lo que significa que no recuerda interacciones pasadas. Aunque es fundamental para la web moderna, la gestión del estado no es compatible con HTTP en sí.
REST: Es una arquitectura para construir APIs sobre la web. Una API RESTful es sin estado, soporta verbos HTTP comunes y devuelve datos en formatos JSON o XML.
En lo personal, aun no entiendo del todo el "Statelessness", pero basta con recordar que no necesitamos guardar un "estado" cuando interactuamos con APIs o cuando el navegador consulta paginas web.
Capitulo 8 - ViewSets and Routers
Los Viewsets y Routers son herramientas de Django REST Framework que aceleran el desarrollo de APIs. Permiten reemplazar múltiples vistas relacionadas con un solo viewset y generar automáticamente URLs, reduciendo la cantidad de código necesario.
Un viewset combina la lógica de múltiples vistas relacionadas en una sola clase. Esto significa que un viewset puede reemplazar varias vistas. Por ejemplo, en lugar de tener cuatro vistas (dos para publicaciones y dos para usuarios), podemos tener dos viewsets.
Los Routers trabajan con viewsets para generar automáticamente patrones de URL. En lugar de tener cuatro patrones de URL, con routers y viewsets, solo necesitamos dos rutas. Normalmente repetimos el mismo codigo cuando hacemos un CRUD con API, los ViewSets nos ayudan siempre y cuando no se necesiten hacer mas validaciones al modelo, y los routers nos ahorran el generar 4 urls.
Aunque los Viewsets y Routers reducen la cantidad de código necesario, tienen una curva de aprendizaje compleja. Es recomendable comenzar con vistas y URLs y, a medida que el API crezca en complejidad, considerar la transición a viewsets y routers. La decisión de cuándo usarlos depende del proyecto y de nuestras necesidades como desarrolladores.
Puedes ver un ejemplo Viewsets y Routers aqui:
Capitulo 9 - Schemas and Documentation
Una vez desarrollada una API, es necesario documentarla adecuadamente para facilitar su uso por otros desarrolladores. Segun el libro, un "Esquema" (schema) es un documento legible por máquinas que describe los endpoints, URLs y verbos HTTP de la API. Sin embargo, para una comprensión humana, es preferible tener una documentación basada en ese esquema.
El estándar actual para documentar una API es la especificación OpenAPI. Para Django REST Framework, el paquete recomendado para generar un esquema OpenAPI en la version 3 es drf-spectacular. Una vez instalado y configurado, se puede generar un esquema de la API como un archivo independiente o servirlo dinámicamente desde una ruta URL de nuestra API.
drf-spectacular soporta dos herramientas de documentación de API: Redoc y SwaggerUI. Ambas transforman el esquema en una documentación fácil de leer y utilizar.
Ejemplo de Redoc: https://wisphub.net/api-docs/