Se ha demostrado que API First es la metodología más rentable para la documentación y definición en las APIs de nuestra organización.
Curso API Owners Fundamentals
Una casa sin planos no es una casa, sino una tienda de campaña.
Definir una API es trasladar el dominio de negocio en forma de recursos a una interfaz fácilmente entendible y consumible. Mediante ella, podemos describir nuestra API en un formato que haga fácil su comprensión y pueda ser leído por máquinas. Es agnóstica a la tecnología, lo que significa que no depende del lenguaje de programación en el que decidamos llevar a cabo su desarrollo. Ahora bien, ¿por qué es tan importante?
Existen varios motivos, entre ellos:
Conceptos básicos
Lo ideal es empezar por la definición.
2. ¿Cómo saber si la definición es legible y comprensible?
Si un desarrollador sin contexto funcional es capaz de consumir la API sin más documentación que la definición, entonces es developer friendly. Hablamos más en detalle de ello aquí.
3. ¿Cómo se definen las operaciones?
Por lo general, mediante los verbos HTTP (GET, POST, etc.), aunque en situaciones concretas puede que no sean suficientes.
4. Idempotencia y seguridad en las operaciones
5. Estado de la aplicación.
Una API REST no guarda estado de la aplicación.
6. ¿Hypermedia?
El uso de enlaces es altamente recomendable, a veces incluso obligatorio.
7.Negociación de contenido
Hay que usar correctamente las cabeceras Accept, Accept-Language, Content-Type y Content-Language.
8. Formatos de E/S
Preferiblemente JSON, pero puede ser cualquiera que necesitemos.
¿Cómo hacer una correcta definición de APIs?
Buenas prácticas:
Generales:
Por ejemplo: ISO 8601 (fechas), ISO 3166 (países), ISO 4217 (divisas)…
2. Usar tipos de datos concretos. Por ejemplo:
1234 Integer String
12,34 Float String
String “S” o “N” -> True o False
3. Ubicar los parámetros en función de su objetivo y naturaleza.
Filtros en query string, árbol de recursos en path, parámetros sensibles en cabeceras o cuerpos de petición.
4. Usar correctamente los códigos de estado en las respuestas.
Códigos 2xx, 3xx, 4xx y 5xx.
5. Definir URLs sencillas, no más de tres niveles. Por ejemplo:
/customers/{idCustomer}
/customers/{idCustomer}/orders/{idOrder}/order-items/{idOrderItem
6. Evitar la ambigüedad en los recursos.
Evitar recursos del tipo /resources, /instances, /items, /objects… Los recursos deben corresponder a entidades de negocio.
7. Definir los recursos en plural.
8. Evitar verbos en las URLs.
Las acciones a realizar sobre los recursos las indican los métodos HTTP.
9. Cuidar la información que se devuelve.
Devolver lo estrictamente necesario, no todo.
Corporativas - Estándar corporativo de definición
1. Políticas de nombrado de recursos.
2. Políticas de nombrado de parámetros.
3. Políticas de nombrado de campos de E/S.
4. Políticas de formatos de E/S y excepciones admisibles.
5. Tamaños máximos de archivos de E/S en caso de que se reciban o devuelvan.
6. Políticas de seguridad y control de acceso.
7. Políticas de versionado (formato, tiempos y nº versiones vigentes).
Es altamente recomendable contar con:
1. Modelo común de datos.
2. Plantillas de definición con elementos comunes y reutilizables.
Es imprescindible contar con:
1. Modelo de respuesta común o respuesta estándar corporativa
2. Modelo común de errores, incluido en la respuesta estándar.
Ejemplo OpenAPI v3
Este estándar permite generar y visualizar la documentación de la API en un lenguaje “natural”. También es posible publicar directamente esta definición en determinadas herramientas de API management. Además, existen multitud de herramientas y plugins que nos permiten exprimir al máximo su potencial, haciendo posible la generación automática de mocks, la conversión entre versiones, etc.
Conclusiones
Las ventajas y posibilidades que nos aportan la definición y establecer unos criterios comunes para llevarla a cabo, convierten este paso en algo muy valioso e importante para cualquier organización.
Enlaces de interés
Blog realizado por Jacob de las Peñas
¡Habla con nuestros expertos!
