Las Interfaces de Programación de Aplicaciones (API, por sus siglas en inglés) constituyen uno de los servicios de intercambio de información y acceso a datos más comunes en la actualidad.
Complementan la disponibilidad de datos en ficheros descargables y aportan una serie de ventajas que hacen que sea un medio de acceso y consumo de datos imprescindible en cualquier iniciativa de Datos Abiertos. Además es el mecanismo de acceso idóneo para publicar datos con alta frecuencia de actualización como los datos en tiempo real o dinámicos.
Es habitual usar APIs para acceder a datos meteorológicos, de transporte público o los producidos por sensores de monitorización urbanos, entre otros datos de alto valor. No obstante, las APIs son adecuadas para consumir todo tipo de datos de forma automática siendo posible, además, ajustar la descarga exclusivamente a los datos requeridos.
Implementación de APIs
La documentación de una API es uno de sus elementos más importantes y constituye un acuerdo entre las partes, a modo de un contrato que describe el comportamiento y las condiciones de uso de la API: específica qué operadores están disponibles y qué se va a obtener como respuesta.
Las APIs se implementan siguiendo algún modelo arquitectónico o guía de diseño que permite definir las reglas que gobiernan una interacción entre sistemas. Un ejemplo de diseño arquitectónico es: REST (Representational State Transfer).
Una característica relevante de este modelo es el uso de estándares abiertos como HTTP/HTTPS, lo cual no vincula las implementaciones de la API en el servidor o de las aplicaciones cliente con ninguna implementación concreta, es decir, ambos componentes se pueden implementar usando lenguajes de programación diferentes, siempre que puedan formular solicitudes y entender respuestas usando protocolo HTTP.
Una API REST se puede implementar utilizando cualquier lenguaje de programación siendo los más habituales: Java, .NET, Python, PHP, Ruby o el más reciente Node.js.
¿Cómo funciona una API?
La comunicación entre servidor y clientes sobre la Web se realiza mediante el intercambio de mensajes HTTP en un contexto seguro de interacción. Los mensajes son de dos tipos: peticiones, enviadas por el cliente al servidor para solicitar el inicio de alguna acción para interactuar con recursos de información y respuestas que constituyen la materialización de la acción solicitada.
Cada petición contiene toda la información necesaria para ejecutar la acción requerida, lo que implica que toda la interacción se realiza en un único ciclo y no es necesario recordar ningún estado previo para satisfacerla. Esta es una característica importante de la arquitectura REST. Implica que el contenido solicitado por el cliente no queda almacenado en el servidor entre solicitudes, sino que la información sobre el estado de la sesión la maneja el cliente.
Las acciones u operaciones, también llamadas métodos, se especifican mediante el uso de los denominados verbos HTTP.
En una petición, cada método tiene encomendada una misión. Cualquier sistema que exponga una API REST dispone de los siguientes métodos:
- GET: recupera una representación de un recurso de datos.
- HEAD: recupera la cabecera de una respuesta.
- POST: crea un nuevo recurso de datos.
- PUT: actualiza un recurso existente o lo crea si no existe previamente.
- PATCH: realiza una actualización parcial de un recurso.
- DELETE: elimina un recurso de datos existente.
- OPTIONS: recupera las opciones de comunicación para el recursosolicitado.
¿Dónde se están publicando APIs?
- Dades Obertes Manlleu: https://dadesobertes.diba.cat/dades-obertes/documentacio-tecnica/api
- Aemet OpenData API: https://opendata.aemet.es/
- Catálogo de APIs Abiertas ISTAC: https://www3.gobiernodecanarias.org/aplicaciones/appsistac/api
- EMT mobilitylabs: https://mobilitylabs.emtmadrid.es/
Algunas APIs de éxito y de uso sencillo, están disponibles en empresas que gestionan volúmenes ingentes de información: Amazon, Google Maps, X o PayPal, entre otras. De forma general, están muy bien documentadas y son un referente importante para comprender el alcance de una buena documentación:
- APIdeGithub: https://developer.github.com/v3/
- APIdeGoogleMaps: https://cloud.google.com/maps- platform/?hl=es
- APIdeX: https://developer.twitter.com/
Las API REST gestionan y exponen recursos de información direccionables por medio de Identificadores de Recursos Uniformes (URI), que los diferencia y permiten al acceso a cualquiera de las representaciones disponibles.
Estas APIs pueden manejar diferentes tipos de recursos, incluyendo documentos (instancias individuales), colecciones (conjuntos de recursos), almacenes o ‘stores’ (repositorios gestionados por clientes), y controladores (para procesos específicos). Por ejemplo, mientras una URI como https://datos.ejemplo.com/v1/licitaciones/contratos/{id-contrato} representa un documento individual, https://datos.ejemplo.com/v1/licitaciones/contratos hace referencia a una colección completa.
El uso del separador «/ «
El separador «/» se utiliza para indicar relaciones jerárquicas entre recursos:
https://datos.ejemplo.com/v1/licitaciones https://datos.ejemplo.com/v1/licitaciones/contratos https://datos.ejemplo.com/v1/licitaciones/contratos/menores https://datos.ejemplo.com/v1/licitaciones/contratos/menores/servicios
Omisión del separador final
El separador «/» no debe incluirse al final de la URI, ya que no aporta valor semántico:
Correcto: https://datos.ejemplo.com/v1/licitaciones/contratos
Incorrecto: https://datos.ejemplo.com/v1/licitaciones/contratos/
Uso del guion para legibilidad
Se recomienda usar el carácter «-» para mejorar la legibilidad de las URIs:
Correcto: https://datos.ejemplo.com/v1/licitaciones/contratos/{id-contrato}
Incorrecto: https://datos.ejemplo.com/v1/licitaciones/contratos/{idcontrato}
Evitar el guion bajo
El carácter «_» debe evitarse ya que puede quedar oculto en enlaces subrayados:
Correcto: https://datos.ejemplo.com/v1/licitaciones/contrato-menor/{id-contrato} Incorrecto: https://datos.ejemplo.com/v1/licitaciones/contrato_menor/{id_contrato}
El diseño cuidadoso de URIs, prestando atención a los caracteres especiales y su uso apropiado, es fundamental para crear APIs intuitivas y fáciles de usar. La consistencia en el uso de separadores, la omisión del separador final, y la preferencia por guiones sobre guiones bajos contribuyen a una mejor experiencia de usuario y mantenibilidad del sistema. Estas convenciones, aunque parezcan detalles menores, tienen un impacto significativo en la calidad general de la API.
Uso de minúsculas en URIs
La normalización de URIs requiere el uso de letras minúsculas, según la especificación RFC 3986. Es importante notar que solo el esquema y la autoridad (host) no son sensibles a mayúsculas y minúsculas.
Correcto: https://datos.ejemplo.com/v1/licitaciones/contratos
Incorrecto: https://DATOS.EJEMPLO.COM/v1/licitaciones/contratos Incorrecto: https://datos.ejemplo.com/v1/Licitaciones/Contratos
Extensiones de archivo
Las extensiones de archivo son innecesarias y aumentan el tamaño de la URI. El formato debe
especificarse mediante cabeceras HTTP.
Correcto: https://datos.ejemplo.com/v1/licitaciones/contratos
Incorrecto: https://datos.ejemplo.com/v1/licitaciones/contratos.xml
Operaciones CRUD
Las URIs deben identificar recursos, no acciones. Las operaciones CRUD (Create, Read, Update,
Delete) se manejan a través de métodos HTTP:
Correcto: HTTP GET https://datos.ejemplo.com/v1/licitaciones/contratos
Incorrecto: HTTP GET https://datos.ejemplo.com/v1/licitaciones/obtenercontratos
La adherencia a estas prácticas de diseño de URIs no solo mejora la legibilidad y mantenibilidad de las APIs, sino que también garantiza una mayor consistencia y profesionalidad en el desarrollo. El uso de minúsculas, la omisión de extensiones de archivo y la correcta implementación de operaciones CRUD a través de métodos HTTP son fundamentales para crear APIs RESTful robustas y escalables. Estas pautas, aunque simples en apariencia, constituyen la base de una arquitectura API bien diseñada y orientada a futuro.
OpenApi
La especificación OpenAPI (OAS) establece una descripción estándar de interfaz independiente del lenguaje de programación para las API REST, permitiendo tanto a personas como a máquinas descubrir, entender y utilizar las capacidades de un servicio de manera efectiva. Como evolución abierta del proyecto Swagger, OpenAPI, actualmente en su versión 3.0, promueve la interoperabilidad de sistemas mediante interfaces claras y duraderas.
En un único marco de trabajo, OpenAPI facilita el diseño y documentación de APIs Rest, asegura la compatibilidad con estándares establecidos, y permite la generación de interfaces de desarrollo (SDKs) con el nivel de abstracción necesario para que terceros puedan comunicarse eficientemente con la API, garantizando su funcionamiento en diferentes versiones de un mismo lenguaje. Además, ofrece la flexibilidad de personalizar y adaptar la interfaz según necesidades específicas, realizar pruebas de la API, y obtener métricas de uso y análisis detallados.
Una característica particularmente valiosa de OpenAPI es su capacidad de mantener la documentación sincronizada automáticamente con el código de la API: cuando se actualiza el código, la documentación de los métodos, parámetros y modelos de datos se actualiza correspondientemente, asegurando una coherencia perfecta entre implementación y documentación.
Ejemplo de uso de la especificación OpenAPI en el portal de Datos Abiertos de la Unión Europea: https://app.swaggerhub.com/apis/EU-Open-Data-Portal/eu-open_data_portal/0.8.0
Herramientas para la implementación
El ecosistema OpenAPI proporciona herramientas esenciales para el proceso de adaptación y desarrollo.
Swagger Editor resulta fundamental durante la fase de diseño y adaptación, permitiendo la verificación en tiempo real de la validez de la especificación, la visualización previa de la documentación, la detección temprana de inconsistencias y la experimentación segura con diferentes estructuras.
Swagger UI es esencial para la fase de documentación y pruebas, ya que genera una interfaz de documentación interactiva automática, facilita las pruebas directas de endpoints, presenta ejemplos de uso claros y mantiene una experiencia consistente entre diferentes APIs.
Por último, Swagger Codegen es crucial para facilitar la adopción, pues genera código cliente en múltiples lenguajes de programación, minimiza errores de implementación, optimiza el proceso de integración y asegura la consistencia entre diferentes implementaciones.
Seguridad en las APIs
La seguridad de las API y la forma en la que ésta debe implementarse depende en cierta medida del tipo de datos que se transfiere y de la sensibilidad de los mismos. Es razonable pensar que el nivel de protección y autenticación de usuarios necesario para una API transaccional (de lectura / escritura) debe ser mayor que el requerido para una API de solo lectura.
En el contexto de los Datos Abiertos, el foco está en la lectura de datos y en cierta medida el método HTTP que se utiliza fundamentalmente es GET. No obstante, hay una serie de pautas que de forma general deben tenerse en cuenta a la hora de disponer recursos a través de la Web para su consumo por parte de terceros.
Como se ha comentado las API REST exponen recursos que son accedidos y manipulados a través del protocolo HTTP y cuyos intercambios de información pueden ser cifrados de tal forma que mantengan privadas las interconexiones entre sistemas.
De forma paralela es fundamental preservar la integridad de las APIs de usos abusivos o malintencionados de los servicios expuestos.
Por otro lado, hay que valorar el nivel de autenticación requerido a los usuarios de la API con el objetivo de mantener un equilibrio adecuado entre seguridad y maximización del uso de la API.
Antes de abordar la descripción de posibles formas de interacción es necesario recomendar una serie de pautas que siempre deben ser tenidas en cuenta independientemente del nivel de autenticación requerida a los usuarios de la API. Estas recomendaciones se exponen a continuación.
API Security es una iniciativa que promueve la organización de referencia a nivel internacional Open Web Application Security Project (OWASP) que se centra en la recomendación de estrategias y soluciones para entender y mitigar vulnerabilidades y riesgos de seguridad. La iniciativa propone 10 directrices fundamentales para la implementación de las API