Información general
Descubrir APIs
En esta primera sección se guiará e instruirá al lector desarrollador en el concepto de “descubrimiento” de APIs, que es el proceso de encontrar, identificar y acceder a APIs que necesitamos integrar desde nuestro sistema.
Un aspecto clave del descubrimiento de APIs es encontrar una buena documentación. Las especificaciones claras y bien estructuradas facilitan a los desarrolladores entender cómo interactuar con una API, qué endpoints existen, qué datos espera y cómo se deben manejar las respuestas.
Los principales beneficios de este descubrimiento de APIs son:
- Facilitar la integración de servicios o funcionalidades sin necesidad de reinventar la rueda.
- Fomentar la interacción entre plataformas, aplicaciones o sistemas.
- Entender las distintas posibilidades de integración que se ofrecen
Para descubrir las APIs, se proporciona una herramienta web denominada API Portal, que es un marketplace que conecta a los productores de APIs con los consumidores, cubriendo todas las necesidades desde la perspectiva del consumidor.
Proporciona toda la información que los creadores de la API hayan aportado; desde documentación básica hasta documentación más técnica, casos de uso, ejemplos simples y avanzados, SDKs personalizados, etc. Además, ofrece un registro de actualizaciones y versiones de las APIs y la posibilidad de probar la API en el propio API Portal, sin necesidad de realizar ningún desarrollo.
En esta sección, se detallará cómo acceder y/o registrarse en el API Portal, así como las diferentes secciones que contiene, con detalle para navegar entre ellas y aprovechar al máximo sus capacidades.
Acceso autenticado al API Portal
Como en todos los sistemas autenticados, será necesario autenticarse para poder iniciar sesión en el API Portal. De esta manera se asegura que solo usuarios autorizados puedan gestionar y consumir las APIs disponibles.
- Username: nombre de usuario asociado a su cuenta en el API Portal.
- Password: contraseña asociada a su cuenta en el API Portal. Si la cuenta fue creada por un administrador y es la primera vez que accede, deberá utilizar la clave temporal proporcionada y modificarla posteriormente.
- Forgot password: vínculo para poder recuperar su contraseña en caso de haberla olvidado.
- Remember me on this computer: permite que el portal recuerde su nombre de usuario en el dispositivo actual. La contraseña no será recordada.
- Continue: valida las credenciales ingresadas. En caso de que la autenticación sea exitosa y navega al panel principal del API Portal.
- Create Account: si no tiene una cuenta de acceso, tiene que pulsar aquí para registrarse (Ver siguiente sección).
Proceso de registro
Para crear una nueva cuenta en el API Portal, será necesario crear un usuario. Este usuario servirá como identificador principal en el API Portal. Si el nombre de usuario es válido, se presentará un formulario con el resto de datos que es necesario completar.
Tras ingresar un nombre de usuario, se redirigirá a una pantalla que contiene el resto del formulario de registro. Esta pantalla recopilará la información necesaria para completar la creación de la cuenta.
- First Name: nombre de la persona / entidad que se está registrando (obligatorio).
- Last Name: apellidos de la persona / entidad que se está registrando (obligatorio).
- Password: contraseña que va a usar para acceder (obligatorio).
- Confirm password: la misma contraseña anterior para validar (obligatorio).
- Email: dirección de correo electrónico válida (obligatorio).
- Organization: nombre de la organización a la que pertenece.
- Telephone: número de teléfono fijo.
- Country: seleccione su país de origen de una lista desplegable.
- Mobile: número de teléfono móvil.
- URL: URL a su perfil profesional o página web.
- Aceptar términos y servicios: Antes de completar el registro, el usuario debe leer y aceptar los términos y condiciones del API Portal.
Todos los datos introducidos durante el proceso de registro en el API Portal ayudarán a los administradores del sistema en la gestión y organización de las cuentas. Además, al suscribirse a una nueva API, el creador de dicha API podrá también visualizar el nombre, apellidos, organización y correo electrónico.
Secciones del API Portal
El API Portal se divide en dos secciones principales:
- Módulo APIs: proporciona acceso a la lista de APIs disponibles,
- Módulo Aplicaciones: es donde se gestionan las aplicaciones creadas por el usuario y su organización.
Para poder navegar entre los diferentes portales utilizaremos el menú que se muestra a continuación:
Es importante destacar que el módulo de APIs no requiere estar autenticado en el sistema. Puede haber APIs que sean públicas y puedan ser consultadas sin necesitas de autenticarse. Lo que no será posible será realizar pruebas ni acceder al módulo de aplicaciones.
Módulo APIS
Aquí se mostrarán todas las APIs que tiene disponibles el usuario. Incluye funcionalidades de filtrado para buscar y explorar APIs de manera eficiente, facilitando la identificación de las más adecuadas para sus necesidades.
- APIs disponibles: Muestra todas las APIs accesibles para el usuario, cada una enlazada a su panel de control correspondiente.
- Barra de búsqueda: Permite buscar APIs por nombre, facilitando la exploración cuando hay un gran número de APIs.
- Filtro de producción y prototipos: Permite mostrar solo las APIs productivas o las que están en fase de prototipo.
- Filtro por etiquetas y categorías: Permite filtrar las APIs por categorías y etiquetas.
- Espacio personal del usuario: Permite al usuario iniciar o cerrar sesión además de cambiar su contraseña.
A continuación, se mostrará un ejemplo de filtrado por categorías y etiquetas; para ello, se proporcionará un breve contexto. Se han creado cuatro APIs, como se muestra en la imagen a continuación. Estas APIs se han categorizado en las categorías “PetStore” y “PizzaShack”, y se han etiquetado con “Producción” y “Testing” para optimizar el filtrado.
Si usamos la opción de filtrado por categorías (Petstore), solo se mostrarán las APIs “subrayadas” en azul.
Si usamos la opción de filtrado por etiquetas (Testing), solo se mostrarán las APIs marcadas con el recuadro verde de “Testing”.
Vista general
Al pulsar sobre una de las APIs, se mostrará su vista general, que presenta diversas acciones y opciones para interactuar con los recursos disponibles. A continuación, se describe esta pantalla.
- Visión General: Muestra información general de la API seleccionada, como el autor, la versión, la URL de acceso, el número de suscripciones y otros detalles.
- Suscripciones: Permite gestionar y visualizar las suscripciones activas del usuario hacia la API, y ofrece la opción de crear una nueva aplicación con una suscripción integrada a la API seleccionada.
- API Console: Permite realizar pruebas sobre la API.
- Comentarios: Permite ver y agregar comentarios sobre la API, facilitando el feedback y la comunicación entre usuarios y desarrolladores.
- Documentación: Proporciona acceso directo a la documentación oficial de la API, incluyendo detalles sobre endpoints, métodos de autenticación y ejemplos de uso.
- SDK: Permite descargar o acceder a kits de desarrollo de software para facilitar la integración de la API en diferentes plataformas y lenguajes de programación.
- Plan de negocio: Planes de uso ofrecidos por el creador de la API.
- Descarga de Swagger: Facilita la descarga de la definición de la API.
- Documentos: Documentación subida por el creador de la API disponible para su descarga por el consumidor.
- Suscripciones: Permite visualizar la cantidad de suscripciones activas de la API actualmente.
Suscripciones
Antes de explicar esta pantalla y sus posibilidades, es necesario explicar y entender qué es una suscripción.
Si tomamos una suscripción a una plataforma de streaming como analogía a las suscripciones a las APIs, podemos intuir qué significa suscribirse a una API. Al igual que en la plataforma, tú, cliente, te suscribes con unos datos de acceso (los de acceso al API Portal) para tener disponibles un conjunto de recursos (cada una de las operaciones de la API), algunos de los cuales son gratuitos y otros de pago (también puede haber APIs cuyo consumo implique un coste).
Cuando el propietario de la plataforma actualiza recursos, no tienes que hacer nada en especial para disfrutar de ellos. En las APIs es igual; cuando el creador actualiza una API, ya sea añadiendo/eliminando operaciones o parámetros de estas, información, documentación, etc, no necesitas hacer nada, la tendrás disponible para usarla.
En cambio, aparece un concepto nuevo para poder suscribirnos a las APIs, que es el de “aplicación”. Aunque se explicará más a fondo en la sección del Portal de aplicaciones, ahora mismo entendamos una aplicación como una representación lógica de una aplicación física como una aplicación móvil, una web, un dispositivo…
Ahora sí, vamos a ver las distintas partes de esta pantalla.
- Asistente de suscripciones: Guía paso a paso para suscribirse a una API, seleccionando el plan de suscripción y generando las claves para su uso.
- Aplicaciones suscritas: Muestra los nombres de las aplicaciones con las que nos hemos suscrito a esta API, su nivel de throttling, el estado y nos da la posibilidad de ver/generar claves para los entornos de pruebas y producción, así como dar de baja la suscripción.
- Anular suscripción: Permite anular la suscripción de la aplicación a la API, evitando futuras interacciones y acceso a los recursos.
- Administrar Aplicación: Redirige al detalle de la aplicación suscrita para gestionarla.
API console
La consola de API permite realizar pruebas sobre las distintas operaciones de la API desde el mismo API Portal, sin necesidad de realizar ninguna implementación.
Vamos a dividir esta consola en dos partes para facilitar su comprensión.
Seguridad y Gateway
En función del tipo de seguridad definido para la API, podremos escoger una u otra (OAuth2, API Key, Basic Authentication). En el caso de las dos primeras, aparecerá un desplegable con las aplicaciones que tenemos suscritas para escoger una de ellas, con el fin de usar sus claves generadas. Si escogemos básica, tendremos que introducir nuestro usuario y contraseña.
A continuación, escogeremos el tipo de clave que vamos a usar, podríamos decir el entorno en el que vamos a probar (producción o sandbox). Al pulsar el botón para obtener las claves de prueba, las obtendrá de la aplicación seleccionada anteriormente. En el caso de haber escogido el tipo de seguridad básica, esta opción no aparecerá.
Por último, seleccionaremos el gateway del entorno en el que se hará la prueba. Puede que existan APIs desplegadas en varios gateways, ya sea con el fin de distinguir entornos, balanceo de carga, público/privado, etc.
Como se puede ver al final de la imagen, también se da la posibilidad de descargar una colección de pruebas de Postman y también descargar el contrato de la API.
Servidor y recursos
Esta segunda parte comenzará con la selección del servidor, por ejemplo, uno para http y otro para https.
A partir de aquí, se muestran todos los recursos disponibles de la API. Se pueden enviar solicitudes, ajustar parámetros y observar la respuesta de la API bajo distintas condiciones, facilitando la validación de su funcionamiento antes de la integración desde nuestro sistema.
Los recursos se agrupan por etiquetas, bajo la etiqueta default se mostrarán aquellos no etiquetados.
Para probar los recursos de la API, hay que acceder a cada uno de ellos de forma individual. Dentro del recurso seleccionado, utiliza el botón "Try It Out" para desplegar un menú que permite ejecutar el recurso y recibir los resultados.
Se mostrará la información proporcionada por el creador para facilitar la comprensión del consumidor:
- Parámetros: datos enviados en la URL.
- Cuerpo de la petición: datos enviados en el cuerpo de la solicitud en peticiones.
- Respuestas: respuestas que el servidor puede devolver tras realizar las peticiones.
Tras rellenar los posibles parámetros o cuerpo de la petición, utiliza el botón "Execute" para enviar la petición y ver la respuesta a ese caso en particular.
- Execute: realiza el envío de la petición.
- Clean: elimina los resultados de la ejecución anterior y restablece los campos de salida para una nueva solicitud.
- Curl: muestra el comando curl generado para enviar la solicitud.
- URL de la Petición: indica el endpoint al que se ha enviado la solicitud.
- Respuesta del Servidor: presenta la respuesta del servidor a la solicitud enviada.
Comentarios
En esta ventana podremos ver los comentarios que otros usuarios e incluso el propio creador de la API han realizado, incluyendo observaciones, preguntas y sugerencias. La interfaz permite responder directamente a estos comentarios, facilitando la comunicación, la resolución de dudas y el seguimiento de tareas entre los desarrolladores y el creador de la API.
Documentación
En esta ventana, por defecto, se mostrará la información referente al contrato de la API, con posibilidad para navegar por los recursos, métodos de autenticación, esquemas de objetos, etc.
Además, incluye un menú desplegable que ofrece acceso a los diferentes documentos proporcionados por el creador de la API.
SDK
En esta sección, el desarrollador puede descargar SDKs en varios lenguajes para integrar la API en su sistema.
Un caso particularmente interesante es el SDK de Jmeter, que genera varios scripts de Jmeter divididos por etiquetas de recursos y un csv con casos de prueba para realizar pruebas de rendimiento de la API.
Módulo aplicaciones
El Portal de Aplicaciones permite a los usuarios crear y gestionar aplicaciones, necesarias para suscribirse a las APIs disponibles.
Una aplicación es una representación lógica de una aplicación física, como una aplicación móvil, una aplicación web, un dispositivo, etc. Si una aplicación necesita consumir una API, debe suscribirse a la API requerida en un plan de negocios seleccionado, que determina la cuota de uso que se le permite a la aplicación. Una sola aplicación puede tener varias suscripciones a API. Cada aplicación tiene un par de clave y secreto de consumidor. Las solicitudes a las API suscritas se autentican a través de los tokens generados con las credenciales de seguridad mencionadas anteriormente.
Las aplicaciones le permiten:
- Generar y usar una sola clave para varias API.
- Suscribirse varias veces a una sola API con diferentes Acuerdos de Nivel de Servicio (SLA)/planes de negocios que funcionan en función de cada token de acceso.
- Agregar una nueva aplicación: permite crear una aplicación.
- Listado: lista las aplicaciones creadas con su propietario, política de cuota de uso compartida por token de aplicación, estado de la aplicación y número de APIs a las que se ha suscrito. Si pulsamos en el nombre, podemos acceder al detalle de la aplicación (generación de credenciales, gestión de suscripciones, etc.)
- Editar: permite modificar el nombre, la cuota de uso compartida y la descripción de la aplicación.
- Eliminar: Este botón elimina la aplicación, desvinculándola también de cualquier suscripción a APIs asociada.
Creación de una aplicación
- Nombre de la aplicación: el nombre con el que vamos a identificar a la aplicación.
- Cuota compartida por token de aplicación: este campo permite seleccionar el límite de solicitudes que pueden realizarse utilizando un token de acceso generado por la aplicación. Es decir, tiene en cuenta todas las peticiones que se realizan a todas las APIs a las que está suscrita.
- Descripción de la aplicación: breve descripción de la aplicación. Esta descripción tiene como objetivo facilitar la comprensión del propósito y contenido de la aplicación.
Detalle de aplicaciones
Al acceder al detalle de la aplicación, lo primero que se muestra son los mismos datos y opciones que en el listado general de aplicaciones existentes (nombre, cuota, estado, editar y eliminar).
Además, permite la gestión de claves de prueba y producción además de las suscripciones.
NOTA: las ventanas de OAuth2 tokens y API Key son iguales tanto en producción como en pruebas, cambiando el nombre del entorno, por lo que se explicará la funcionalidad como tal de forma genérica.
OAuth2 Tokens
Desde esta ventana, podremos realizar la configuración necesaria para generar un par de clave y secreto del consumidor generados para la aplicación en el entorno seleccionado, con el fin de poder generar tokens para acceder a la API. Esta clave, una vez generada, se convierte en el identificador único de la aplicación, similar a un nombre de usuario, y se usará para autenticar.
Si ya han sido generadas anteriormente, podremos ver la clave que se generó. El secreto se mantiene oculto pero permite mostrarlo y copiarlo.
A continuación, se muestran los endpoint de solicitud y revocación de token, que tendremos que usar en nuestra implementación para solicitar un token y revocarlo, además de las distintas formas posibles de generar el token de acceso.
Si se ha seleccionado como uno de los tipos, Code, se activará el campo de callback URL donde hay que especificar una URL designada para recibir el código de autorización que será usado posteriormente para obtener el token.
Ahora tendremos que configurar los tiempos de expiración de los distintos tokens, en función de la configuración realizada (token de acceso de la aplicación, token de acceso del usuario, token de refresco e id token; usado en el contexto de OpenID Connect).
Por último, se muestran ciertas configuraciones que podemos activar o desactivar.
- PKCE: la clave de prueba para el intercambio de código (PKCE) es una medida de seguridad que se utiliza habitualmente para proteger las aplicaciones que se ejecutan en el mismo dominio. Por ejemplo, dos aplicaciones móviles que se ejecutan en un solo dispositivo pueden obtener el código de autenticación de la otra aplicación y solicitar un token si el dominio es el mismo. Si es nuestro caso de uso, activaremos esta casilla.
- Soporte de PKCE en Texto plano: está asociado a la activación de PKCE. Si la marcamos, el verificador y el retador de código utilizados estarán en texto sin formato. La forma recomendada es utilizar un algoritmo SHA 256, que es el valor predeterminado cuando esta opción no está seleccionada.
- Cliente Público: esta opción permitirá que el cliente se autentique sin el secreto.
API Key
Desde esta ventana, podremos generar una clave de API que podrá ser usada en las APIs que tengan configuradas este tipo de autenticación. Al generar un “api_key”, se pueden aplicar dos tipos de restricciones. Por defecto no se aplicará ninguna.
Restricción por IP: solo las direcciones IP o rangos de IPs especificados en esta opción podrán usar el token generado.
Restricción HTTP: solo las referencias HTTP especificadas pueden usar el token generado.
Suscripciones
Desde esta ventana, podremos gestionar las suscripciones de la aplicación, así como suscribirnos a otras APIs disponibles.
La opción de Suscribir APIs permite suscribirse a las distintas APIs disponibles, indicando el plan de suscripción.
En el listado de aplicaciones ya existentes, podremos ver el estado del ciclo de vida de la API, el plan con el que nos hemos suscrito y el estado de nuestra suscripción (bloqueado o no bloqueado). Además, tenemos la opción de editar el plan de suscripción y de cancelar la suscripción a la API seleccionada.
Si pulsamos en el nombre de una de las APIs del listado, podremos ver el detalle de esta.
Crear el cliente consumidor
En este apartado se explicarán los pasos necesarios para crear un cliente que vaya a consumir una API. Para ello, primero se abordará cómo suscribirse a la API, y después cómo generar las credenciales que usaremos para que el cliente se comunique con la API.
Es importante informar en este punto que, como vimos en la sección de SDK, hay muchos lenguajes disponibles en el API Portal y, además, cada uno puede hacer su aplicación en el lenguaje que desee; por tanto, lo que se mostrará aquí será un ejemplo y explicación de lo que proporciona el SDK para poder integrarse con la API.
Cómo suscribirse a una API
Lo más importante que necesitamos saber es que, para poder hacer uso de una API, es necesario suscribirnos a ella.
Como hemos ido viendo en las secciones anteriores de la guía, para poder suscribirnos a una API, es necesario haber creado una aplicación (ver sección Creación de una aplicación)
Una vez creada la aplicación, accederemos a su menú Suscripciones y pulsaremos el botón de suscribir API, lo que nos mostrará todas las APIs disponibles con su versión y un desplegable con los planes de suscripción disponibles.
Si ya estamos suscritos a alguna, pondrá estado Suscrito y no se podrán realizar ninguna acción.
Tras finalizar el proceso de suscripción, las APIs seleccionadas aparecerán en el listado de suscripciones de la aplicación.
Cómo generar credenciales
En esta sección se detalla, en función del tipo de seguridad, cómo obtener los datos que serán necesarios para poder autenticar/autorizar la aplicación contra la API y cómo se envían.
En el caso de usar OAuth2 o seguridad básica, el envío de la clave/token se hace a través la cabecera Authorization de la petición.
En el caso de usar API Key, el envío de la clave se hace a través de la cabecera ApiKey de la petición.
Si la seguridad escogida es básica (usuario y contraseña), se codificarán el usuario y contraseña en Base64 como “usuario:contraseña” y se añadirán a la cabecera precedidos de la cadena “Basic”. Authorization: Basic Base64(usuario:contraseña).
Si la seguridad escogida es mediante API Key, tendremos que pulsar el botón de Generar clave en el entorno que necesitemos, dentro de las opciones del menú de aplicaciones. Esta clave generada es la que se manda en la cabecera ApiKey.
Si la seguridad escogida es OAuth2, seguiremos la guía para configurar la clave OAuth2, pulsando el botón de generar claves para finalizar el proceso. Si, en esta misma ventana, subimos al principio, veremos que donde antes ponía que no había clave y secreto, ahora si aparecen.
NOTA: si fuera necesario regenerar la clave y el secreto, podemos darle a eliminar claves o al final de la ventana a actualizar.
En este caso, el token que hay que enviar en la cabecera, se genera realizando una petición a una URL con la clave y el secreto recién obtenidos. Esta url y el formato, los podemos ver desde el botón de CURL para generar el token de acceso.
Como podemos ver en el ejemplo, se le pasa el parámetro grant_type y en la cabecera Authorization, se mandan la clave y secreto como si fuera la autorización básica que se ha indicado anteriormente. La respuesta a esta petición es un objeto json que incluye el parámetro access_token. El valor de ese parámetro es el que incluiremos en la cabecera Authorization, precedido de la cadena Bearer. Authorization: Bearer <token generado>.
NOTA: si necesitamos añadir un scope particular para la generación del token, añadiremos en la petición -d “scope:<nombre_scope>”
Guía de creación del cliente
En esta sección se explicará cómo podemos integrar nuestro desarrollo con la API a la que nos hemos suscrito. Para ello, accederemos a la sección SDK de la API seleccionada y nos descargaremos aquella que mejor nos convenga.
Nos descargará un fichero zip con el nombre NombreApi_Version_lenguaje.zip. Al descomprimirlo, en función del lenguaje, tendremos una estructura de carpetas y ficheros distinta. El fichero más importante que tenemos que abrir es el README.me para ver cómo tenemos que usar el SDK desde nuestra aplicación (generar artefacto Maven, publicar librería node, …).
Ejemplo de integración con SDK de Java
A continuación, vamos a ver un ejemplo, una vez generada la librería de Java, cómo podemos hacer uso de ella en un proyecto SpringBoot con Maven.
Lo primero es agregar la dependencia del SDK al fichero POM para vincularlo correctamente. Por ejemplo:
<dependency>
<groupId>org.wso2</groupId>
<artifactId>org.wso2.client.PetStore</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
Utilizando el ejemplo proporcionado en el archivo README.md, se explicarán los diferentes objetos del SDK, detallando su propósito y funcionamiento.
En primer lugar, se encuentra el cliente de la API (ApiClient), responsable de establecer la conexión con el servidor y actuando como el punto de entrada para todas las interacciones con la API.
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("<URL Servidor del API Porta>");Después de su inicialización, es necesario instanciar y configurar el token de autenticación, que se utilizará en cada solicitud para asegurar el acceso a los recursos de la API. El objeto OAuth, en este caso, no contiene la lógica para obtener los tokens de acceso, sino que únicamente se encarga de almacenarlos.
OAuth OauthToken = (OAuth) defaultClient.getAuthentication("default");
OauthToken.setAccessToken("Token de acceso");En caso de necesitar extraer este token, se puede hacer utilizando Spring Security o manualmente mediante una llamada con HttpClient.
Finalmente, se tiene la instancia de la API, que será la encargada de ejecutar las operaciones específicas hacia los endpoints del servicio. Esta instancia, asociada al cliente previamente configurado, permite realizar acciones concretas, como obtener información, crear, actualizar o eliminar recursos dentro de la API.
DefaultApi apiInstance = new DefaultApi(defaultClient);
apiInstance.delete();NOTA: aunque el SDK proporciona lo necesario para conectarse a la API y consumirla, siempre puede modificarse y añadir cualquier método que pueda facilitar su uso.