Invocación a APIS con Swagger y generación de cliente con Swagger Editor

Las APIs creadas en la Plataforma se publican siguiendo el estándar Open API, además las APIs usan Swagger como framework para la creación y publicación de las APIs. Además dentro del ControlPanel se ofrecen las herramientas para consumir las APis vía el UI Swagger para testar las APIs y vía Swagger Editor para generar el código cliente en diversas tecnologías.

Invocar API vía Swagger 

Una vez creada un API en el listado de APIs disponibles por ese usuario podré ver:

Pulsando  visualizaremos su pantalla principal, similar a la siguiente:

En ella dispondremos de varias opciones, en primer lugar, seleccionaremos el protocolo HTTPS (HTTP / HTTPS).

En la parte inferior, aparecen todas las peticiones que están disponibles para la API seleccionada, junto con la identificación que le hayamos dado en la definición de la API (Para los casos en que se encuentren palabras entre llaves {}, implica que hay parámetros de entrada adicionales a los básicos, cuyo identificador se encuentra entre las mismas).

Existen varias opciones dentro de los tipos de consultas que se hayan configurado, las cuales se muestran también en esta pantalla: GET, POST, PUT, DELETE.

 Accediendo a una de las consultas, podemos distinguir 2 bloques diferenciados:

-          Parameters: Donde se describen los parámetros necesarios para la realización de la consulta.

-          Responses: En la que se especifican posibles códigos de respuesta.

Podemos probar la consulta haciendo click en el botón “Try it out” situado en la parte superior derecha para cada tipo de consulta. Esta acción nos permite completar los campos variables de la consulta con nuestros datos. Uno de ellos, será común a todas las consultas, el token de acceso, cuyo nombre de parámetro, de tipo string, es X-OP-APIKey, y el cual podemos obtener desde la opción de Mis APIs>User Tokens.

El resto de parámetros dependerán de como hayamos definido la consulta. Para este caso de ejemplo, nos pide también el parámetro “Site” de tipo string, haciendo referencia a la localización con la cual queremos filtrar nuestra consulta.

Con los datos introducidos correctamente, Ejecutamos la consulta haciendo click en el botón Execute y obtenemos una serie de respuestas del siguiente tipo:

En ellas podemos ver como se han realizado las llamadas REST a la plataforma, junto con las respuestas obtenidas a partir de estas consultas en el formato JSON.

En este ejemplo en concreto, podemos ver como nos devuelve todos los datos que cumplen las condiciones de nuestra consulta.

Invocar API vía Postman utilizando token OAuth2

De la misma forma que hemos utilizado el swagger en el anterior ejemplo, podemos utilizar otro tipo de clientes, en este caso, Postman, demostrando a su vez, que podemos hacer las peticiones mediante el Bearer Token.

Para ello, necesitaremos el token OAuth2, lo podemos obtener entrando en el apartado APIS, localizado en la parte superior derecha de la pagina principal de nuestra plataforma:

Una vez obtenido, lo guardamos, y generaremos en la interfaz del Postman una nueva petición, de tipo GET, y que invoque nuestra url de la API a probar:

Luego, añadiremos los parámetros necesarios mediante el boton Params que nos desplegará un formulario a rellenar, con los parametros que hayamos definido previamente:

Serán necesarios tambien incluir las autorizaciones (Authorization):

Y las cabeceras (Headers):

Como podemos apreciar, Postman nos ha incluido una cabecera de tipo Authorization por haberla configurado en el anterior paso.

Finalmente, enviamos la petición mediante el boton Send.

En la parte inferior podemos visualizar los resultados de la petición, que son los mismos que los obtenidos en el paso anterior, pero habiendo hecho uso de un token de diferente tipo:

Generación de cliente de la plataforma con Swagger Editor

Desde el listado de APIS puedo seleccionar 

También podemos hacer uso del editor de Swagger que nos permite generar un cliente del API seleccionada para diversos lenguajes:

En la acción de menú  seleccionaré Java.

Esto descarga un ZIP con un cliente en Java del API, puedo cargar ese ZIP en mi IDE favorito y configurarlo para que ataque a mi API, para eso:

1. Cargo el proyecto XXX en Eclipse
2. Voy a la clase ApiClient.java donde debo configurar el basePath y el Token:

Private final static DefaultApi api = new DefaultApi();

String xSOFIA2APIKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

api.devuelveLosUltimos10Registros(xSOFIA2APIKey);

3. Pruebo el cliente.