Practicas recomendadas en el diseño de tus APIs
Al principio de comenzar a aprender a programar creía firmemente que la clave para el éxito en este mundo era dominar la mayor cantidad posible de lenguajes de programación.
Invertía mucho tiempo en tutoriales en línea, participando en foros de programación y practicando con proyectos personales con el lenguaje o Framework de moda, Go, Deno, Astro, Rust...
Estaba convencido de que mientras más lenguajes de programación aprendiera, más valioso sería como programador.
Estaba equivocado.
Lo que me abrió los ojos fue un reto del Advent of Code de 2020.
El Advent of Code son una problemas de algoritmia que publican durante el Adviento de cada año.
Con conocimiento básicos de programación puedes superar los primeros retos, pero a medida que se avanza no son suficientes.
Ahora no me dejo llevar por las modas de este sector y dedico mi esfuerzo a profundizar en temas como estructuras de datos, algoritmos, paradigmas de programación...
Esta semana te quiero contar lo que pienso que son los puntos esenciales que tienes que tener en cuenta cuando diseñes y programes tus APIs.
¿Qué es una API?
Una API es una interfaz de programación entre aplicaciones (Application Programming Interface).
Vamos a darle un poco de chicha.
Una API es un conjunto de reglas y protocolos que permite que diferentes aplicaciones informáticas se comuniquen entre sí.
Una API actúa como un intermediario que permite que dos programas o sistemas interactúen y compartan datos o funcionalidades de manera controlada y segura.
Las reglas que te voy a contar son válidas indendientemente del tipo de API que quieras programas, REST, SOAP, WebSocket o RPC.
Mi intención con las siguientes reglas es que tu API sea fácil de utilizar, sea concisa y difícil de utilizar indebidamente.
Al turrón.
¿Cuáles son las recomendaciones para el diseño de una API?
Mis recomendaciones para el diseño de tus APIs son:
- Usa sustantivos en lugar de verbos
- Usa sustantivos en plural
- Se coherente
- Mientras más simple mejor
- Utiliza los códigos de estado apropiados
- Realiza un manejo apropiado de los errores
- Buenas prácticas de seguridad
- Usa paginación
- Versiona tu API
- Documenta
Utiliza sustantivos en lugar de verbos
No utilices verbos en tus endpoint.
El nombre de la ruta debe contener los sustantivos que identifican el objeto al que pertenece el endpoint al que accedemos o modificamos.
Por ejemplo, en lugar de utilizar /getAllOrders para obtener todos los pedidos, utiliza /orders
Utiliza sustantivos en plural
Utiliza la forma plural para sustantivos de recursos porque se adapta a todos los tipos de endpoints.
Por ejemplo, en lugar de utilizar /order/:id/, utiliza /orders/:id/.
Se coherente
Cuando te digo de ser coherente, me refiero a ser consistente y predecible.
Cuando definas un endpoint, los demás deberían comportarse de manera similar.
Por lo tanto, utiliza el mismo caso para los recursos, los mismos métodos de autenticación para todos los endpoints, los mismos encabezados, los mismos códigos de estado, etc.
Mientras más simple mejor
Debemos hacer que los nombres de todos los endpoints estén orientados a los recursos.
Si quieres definir una API para los pedidos, la describiremos como:
/orderspara obtener todos los pedidos/orders/isdfs232para obtener un pedido específico
Utiliza los códigos de estado apropiados
HTTP nos proporciona una multitud de códigos de estado, úsalos de forma apropiada.
No abuses de códigos de estado pero usa los mismos para devolver resultados similares, por ejemplo:
- 200 para una respuesta satisfactoria general
- 201 para el almacenado satisfactorio, por ejemplo un nuevo registro en la BBDD
- 400 para solicitudes con errores
- 401 para solicitudes no autorizadas
- 5xx para errores internos
Te dejo un enlace a un artículo con todos los códigos de estado HTTP.
Códigos de estado de respuestas HTTP
En este artículo te explicaré qué son y cómo interpretar los códigos de estado de respuesta HTTP.
Realiza un manejo apropiado de los errores
Debemos de evitar cualquier confusión cuando ocurre un error.
Debes manejar los errores adecuadamente y devolver un código de respuesta indicando lo sucedido (de errores 400 a 5xx).
Devuelve detalles en el cuerpo de la respuesta junto con el código de estado del error.
Buenas prácticas de seguridad
La comunicación entre un cliente y un servidor tienes que estar protegida, lo que significa como mínimo:
- Comunicación cifrada; usar siempre SSL/TLS, sin excepciones
- Autenticación mediante claves API, que deben pasarse mediante un encabezado HTTP personalizado con una fecha de caducidad
Usa paginación
Usa la paginación para devolver una gran cantidad de datos, ya que esto hará que nuestra API esté preparada para el futuro.
Te recomiendo utilizar pagina o page y numero_paginas o page_size.
Por ejemplo, /orders?page=10&page_size=20
Versiona tu API
Es importante versionar las API desde la primera versión, ya que nuestras APIs podrían tener diferentes usuarios.
Esto permitirá a nuestros usuarios evitar verse afectados por cambios que podamos realizar en el futuro.
Las versiones de API se pueden pasar a través de encabezados HTTP o parámetros de consulta/ruta, por ejemplo, /v1/orders/ifdf234
Documenta
Documenta tus APIs porque la API será tan buena como su documentación.
Los documentos deben mostrar ejemplos de ciclos completos de solicitud/respuesta.
Hasta luego 🖖
