API Owner Fundamentals APIs Technology
BLOG definición en las APIs

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

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:

BLOG-icon-web-cloudappi-9
BLOG-icon-web-cloudappi-8
BLOG-icon-web-cloudappi-7
BLOG-icon-web-cloudappi-6
BLOG-icon-web-cloudappi-5

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. Modelo común de datos.

2. Plantillas de definición con elementos comunes y reutilizables.

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

BLOG-img-web-cloudappi-2

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

// ¿Quieres saber más sobre la importancia de la definición de APIs?

¡Habla con nuestros expertos!

Author

CloudAPPi

Leave a comment

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *