La especificación Open API, originalmente conocida como la especificación Swagger, es una especificación para interfaces procesables por máquinas, descritas en archivos para ser producidas, consumidas y virtualizadas en servicios web RESTful. 

Originalmente parte de framework Swagger, se convirtió en un proyecto separado en 2016, vigilado por la iniciativa OpenAPI, una colaboración de open source de la Linux Foundation.

Las interfases RESTful diseñadas dentro de nuestras soluciones se alinean a este estándar para garantizar la portabilidad entre diferentes API Managers.

De igual forma, BIAN emite sus interfaces por medio de archivos Swagger, que también están alienados a este estándar.

La especificación que utilizamos actualmente es la Open API 3.0.2, la cual  se versiona utilizando Semantic Versioning 2.0.0 https://semver.org/spec/v2.0.0.html (semver) y sigue la especificación semver.

Utilizamos el principio HATEOAS, Hypermedia As The Engine Of Application State (hipermedia como motor del estado de la aplicación). Definido como cuando el servidor nos devuelve la representación de un recurso (JSON, XML…) parte de la información devuelta serán identificadores únicos en forma de hipervínculos a otros recursos asociados.

La restricción HATEOAS propone que el cliente y el servidor se comuniquen completamente utilizando el hipermedia.

Existen varias ventajas al usar hipermedia:

  • Permite a los diseñadores de API en lugar de incluir todo lo que pueden en cada respuesta, para proporcionar una cosa correctamente y enlaces hipermedia a puntos finales relacionados y así desacoplar el diseño.
  • Ayuda a que una API evolucione y madure con más gracia
  • Proporciona al usuario los medios para explorar la API más profundamente

Para comprender más a fondo cómo es que API IFScore utiliza el principio HATEOAS puede visitar un ejemplo en:

https://www.adictosaltrabajo.com/2013/12/02/spring-hateoas/

API IFScore tiene un nivel 3 de madurez según el modelo de madurez de Richardson. El estudio de un centenar de diseño de servicios web diferentes se dividió en cuatro categorías en función de cuanto cumple con REST, estas categorías se dividen en función de tres factores:

  1. URI
  2. Método HTTP y
  3. HATEOAS (Hypermedia)

Copyright © 2020 Grupo Aullox S.A de C.V.