La importancia de la definición en las APIs

Curso API Owner Fundamentals

“Una casa sin planos no es una casa, sino una tienda de campaña”

Esta frase nos gusta mucho al equipo de CloudAPPi porque para nosotros representa claramente lo que es la API Definition. La definición (o especificación) de una API es un elemento muy importante de su desarrollo. Por ello, varios warriors del equipo pudieron profundizar sus conocimientos en relación con la API Definition durante el Curso de API Owner Fundamentals de la Fundación APIAddicts.

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:

Ayuda a visualizar la API y entender sus atributos, facilitando la colaboración y el entendimiento de las partes implicadas en su desarrollo.

Ayuda a las personas externas a entender la API y lo que puede hacer.

Facilita la creación de tests. Con ella sabemos qué pinta tienen las respuestas de nuestra API.

Podemos generar implementaciones de código y SDKs en distintos lenguajes de programación

Podemos crear una live API mediante API gateways como el de Amazon, Azure, Apigee o Google Cloud, ya que se basan en definiciones de API.

Conceptos básicos

1. ¿Empezamos por la definición o por la implementación?

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 practicas

Generales

1. Usar estándares internacionales para dar formato a datos concretos (fechas, países, monedas...).

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.

Generales

1. Usar estándares internacionales para dar formato a datos concretos (fechas, países, monedas...).

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.

Generales

1. Usar estándares internacionales para dar formato a datos concretos (fechas, países, monedas...).

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

Se debe contar con:

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

Actualmente, entre los estándares de definición de APIs que existen, el más comúnmente utilizado es la especificación OpenAPI (OAS). Está basada en la especificación Swagger y define estándares RESTful para APIs. Esta especificación mapea recursos y operaciones para una API. La versión 2 se conoce como Swagger, aunque realmente Swagger es un conjunto de herramientas de edición, generación de documentación y código.

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

La definición de una API debería ser el primer paso antes de comenzar el desarrollo, ya que permite detectar problemas antes de que surjan y establecer con coherencia y solidez qué va a hacer nuestra API y cómo, involucrando a todas las partes del proceso.

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.