Etapas de Procedimiento de Diseño de API

Lo primero que tenemos que tener claro en nuestra API son los recursos que van a sostener en intercambio de información requerida.

Estos recursos API han de definirse en base a estructuras de datos comunes para toda la organización que no se asemejan a los modelos de datos de los sistemas. Esto se debe a que se busca esa independencia de recursos que sean válidos para todos los sistemas y que, por tanto, faciliten la comprensión de los mismos a cualquier consumidor de cualquier API de la compañía. Estas estructuras comunes han de estar definidas de antemano en la compañía.

Por tanto, partiendo de las estructuras de datos comunes definimos qué recursos API necesitamos para dotar a los consumidores de nuestra API de la información requerida y/o las operaciones necesarias.

En esta etapa del procedimiento, hemos de revisar las estructuras comunes existentes, los Documentos OpenAPI que contienen los modelos/esquemas de nuestros recursos, con el fin de iterar sobre los mismos y seleccionar, añadir y/o modificar los recursos necesarios para dar cobertura a la API que vamos a diseñar.

Así mismo, hemos de revisar nuestro diccionario de datos, donde contenemos el lenguaje que hablan nuestras API, para, de la misma forma que hacemos con los recursos, iterar sobre los mismos y seleccionar, añadir y/o modificar los datos/campos necesarios para dar cobertura a la API que vamos a diseñar.

Cuando hablamos de recursos API, nos referimos a entidades funcionales, que pueden estar jerarquizados o no, y que de forma unitaria representan una entidad funcional del sistema: Clientes, Pedidos, Coches, Viviendas, etc.

Y cuando hablamos del diccionario de datos, nos referimos a las propiedades, con sus características, que conforman cada uno de los recursos. Es decir, establecemos los campos de cada recurso para tener un nombre y tipo común en todas las API que requieran de su uso.

Gracias a esto:

• Logramos reducir el tiempo y coste de adaptación constante de unos sistemas a otros
• Reducimos los tiempos de desarrollo
• Dotamos a los desarrolladores de las aplicaciones de estructuras de información con un lenguaje universal dentro de la compañía.

Por otro lado, consumidores externos que requieran hacer uso de nuestras API, tendrán la misma facilidad de adaptación y sencillez de desarrollo a la hora de necesitar consumir diferentes API de diversos sistemas de nuestra compañía. 

¿Por qué? Es fácil, nuestras API se basan en estructuras comunes, con lo que la comprensión de diferentes API se reduce a la comprensión de los recursos comunes a todas ellas.

En segundo lugar, una vez que tenemos definidos los recursos a utilizar, definimos qué representaciones va a soportan nuestra API: XML, JSON, XML y JSON y bajo qué lenguaje vamos a implementar las mismas (JSON, YAML). 

En este curso, vamos a centrarnos en la definición de API REST (o RESTful), es decir, API que se basan en la arquitectura REST.

El tercer paso, muy importante, es definir cómo se va a acceder a los recursos y bajo qué métodos (o verbos).

Como hemos comentado, nuestros recursos pueden estar jerarquizados o no, y para acceder a ellos utilizamos Uniform Resource Identifiers (URIs), que son estructuras jerarquizadas de recursos.

Asociados a cada una de estas URI, definimos los métodos HTTP que van a utilizarse para ejecutar las operaciones habilitadas desde nuestras API. Estos métodos, basados en los estándares HTTP, nos permitirán utilizar mismas URIs asociadas a cada uno de ellos, de forma que podamos especificar qué operaciones vamos a realizar con cada recurso (jerarquizado o no).

Por ejemplo, si queremos operar con un recurso alumno, que forma parte de un recurso colegio, podemos tener una URI del estilo a /colegios/alumnos

Sobre la URI anterior, si deseamos dar de alta un alumno de un colegio, operaremos, bajo dicha URI, con un método POST, mientras que, si queremos obtener un listado de alumnos, podemos operar, bajo misma URI, con método GET.

Unido a la selección del método con el que trabajar, siempre acorde con los estándares, tenemos que tener claro el concepto de idempotencia. La idempotencia se define como la propiedad de realizar la misma acción muchas veces y que, sin embargo, el resultado final sea el mismo que obtendríamos si esta acción solo se realizara una vez.

Es decir, en un ejemplo de realización de un pedido, la idempotencia en este caso aseguraría que, si nosotros lanzáramos la petición de realizar el mismo pedido 10 veces, el resultado final es que el pedido solo se realizará una vez. Este concepto es crítico y hay que tenerlo en cuenta para definir las operaciones a realizar, los métodos que las van a sostener y, en caso de necesidad de asegurar de forma "artesanal" la idempotencia, establecer el mecanismo para ello, y es que no todos los verbos HTTP son idempotentes.

Otro aspecto muy importante a definir, y que implicará la toma de muchas decisiones en el diseño de nuestra API, es el tipo de comunicación que va a ofrecer: síncrona o asíncrona.

Un mismo API puede contener operaciones síncronas, donde el consumidor realiza una petición y espera una respuesta, y operaciones asíncronas, donde se envía la petición y no se espera a que llegue la respuesta, sino que esta será una invocación, también asíncrona, desde el backend correspondiente a la URI de callback que haya indicado el consumidor.

Es vital definir correctamente el tipo de comunicación a la hora de diseñar una API, y esto hay que diseñarlo en base a la combinación de necesidades de negocio, a los propios procesos de negocio, a las arquitecturas planteadas y necesidades/requerimientos técnicos como rendimiento.

Cómo definamos la comunicación de nuestras API definirán el comportamiento de los sistemas, por lo que puedes comprender la necesidad de tener muy claro qué queremos hacer con la API y cómo lo vamos a llevar a cabo.

Como cuarto paso, hemos de definir aspectos como la seguridad, los comportamientos especiales e identificar los posibles errores y diseñar los mensajes asociados a los mismos.

Para establecer la seguridad hemos de tener en cuenta varios aspectos:

• ¿Quién va a consumir nuestra API? Aplicaciones internas, externas, ambas...
• ¿Qué información va a contener el API?
• ¿Es necesario establecer Roles y Permisos específicos?
• ¿Qué normativa de seguridad hay en la compañía?

Respondiendo este tipo de preguntas, conjuntamente con los responsables de negocio, de arquitectura y de seguridad, podremos establecer el tipo de seguridad que vamos a implementar en nuestra API.

Dentro de OAS 3.1.0, tenemos especificadas seguridad por APIKEY, OAUTH, OPENID... como parte de los esquemas de seguridad (security schemes).

Cuando nombramos comportamientos especiales de un API estamos hablando de aspectos tales como paginación, ordenación, cacheado... para lo cual hay que definir dichos aspectos en la API y el backend que va a soportar las operaciones ha de ser desarrollado a tal efecto.

Por último, es muy importante definir las respuestas que va a dar nuestra API, y es muy importante definirlas al principio, en el diseño de la API, de forma que adoptemos diferentes códigos de respuesta (success y/o error) y diseñemos los mensajes de error asociados a cada una de ellas, con el fin de simplificar al máximo tanto la generación y envío desde el backend como, la recepción y procesamiento desde el lado de los consumidores y, como siempre, acordes a estructuras comunes donde mismo código de error genere misma tipología de respuestas funcionales.

El estándar OpenAPI Specification nos indica que debemos de seguir la norma RFC7231 donde se describen los posibles tipos de errores a devolver.

Por último, como quinto paso, hablamos de que una característica de especial relevancia de toda API es que estas son autodocumentadas. Esto quiere decir que la propia API contiene toda la documentación asociada necesaria para que los desarrolladores de aplicaciones puedan entenderla y hacer uso de la misma.

Esta documentación hay que desarrollarla a la vez que desarrollamos la especificación completa de nuestra API, que se basará en el diseño que hayamos realizado de la misma.