Consejos para conseguir el éxito trabajando contra una API de terceros

Imagínate que es tu deber y obligación conectarte a una API de terceros. No hay proyecto sin esa API.

• La documentación brilla por su ausencia.
• Las peticiones se hacen con variables extrañas
• Todo se hace mediante el método POST.

¿Qué mas se puede pedir?

Tu pericia y habilidad vienen al rescate, que seguro que tienes en abundancia.

En este artículo veremos algunas pistas para trabajar contra una API generada por otro proveedor, en el que no podemos cambiar el código y a la que tenemos que ceñirnos para que el proyecto salga adelante. La típica API que proviene de una aplicación de gestión de almacén, un ERP o un CRM.

Tenemos que conectarnos para enviar un pedido, descargar unos datos del catálogo, crear nuevos clientes, actualizar estados de procesos…

No es el caso de API’s bien documentadas y utilizadas por cientos o miles como la de Twitter, Unsplash o Flickr. Son plataformas hechas a medida expuestas al mundo exterior mediante una API a veces no en las mejores condiciones.

Tener una interfaz de acceso a la API separada de nuestro código ¶

Estoy pensando en un software en el que pueda conectarme a la API, hacer peticiones y ver las respuestas. Pero que no tenga nada que ver con la lógica del código.

Es el “cuartel de invierno”, nuestra “guarida”, donde podremos comprobar el funcionamiento de la API y así contrarrestar la falta de documentación o el uso de malas nomenclaturas.

Te aconsejo utilizar Postman, que es gratuito, aunque también puedes usar el Swagger Inspector. Incluso, si ya tienes experiencia de otras ocasiones, puedes crear tu propio frontal de conexión con JavaScript.

Puedes aprender a diseñar y testear API’s con Postman en nuestro curso.

En todos estos sistemas debemos poder guardar la colección de accesos a la API, con los parámetros que tengamos que pasar de autenticación, cuerpo del mensaje o el método de envío (GET, POST, PATCH, DELETE…)

Para todos estos temas de la API te aconsejo escuchar este episodio de mi podcast:

¶

Suscríbete a Web Reactiva

Crear nuestros propios tests ¶

Seguimos sin entrar en nuestro código. ¿Por qué? Porque un elemento externo y desconocido tiene que estar bien testado antes de incorporarlo a nuestra lógica.

Probablemente tengamos que enganchar varias peticiones a la API para poder probar el funcionamiento completo de una feature. Por ejemplo el registro del usuario, su autenticación y un evento relacionado con ese usuario que tiene control de acceso. Nos hace falta mantener un estado o un token para que la API sepa quiénes somos al conectarnos.

En este caso podemos utilizar Postman, que tiene soporte para hacer testing basado en colecciones de peticiones.

Quizás en esta ocasión es mejor crear tests de aceptación desde nuestro script. En mi caso conseguí buenos resultados con Codeception para PHP, aunque también tienes versión para Node con CodeceptJS.

Por supuesto puedes utilizar tu librería de testing favorita, dado que buscamos crear un entorno de confianza donde controlamos las entradas y las salidas a la API para poder dar validez a lo que allí ocurre.

Para que te hagas una idea, y sin entrar en detalles, tendríamos algo así:

$I = new ApiTester($scenario);$I->wantTo('create a user via API');$I->amHttpAuthenticated('service_user', '123456');$I->haveHttpHeader('Content-Type', 'application/x-www-form-urlencoded');$I->sendPOST('users', ['name' => 'davert', 'email' => 'davert@codeception.com']);$I->seeResponseCodeIs(200);$I->seeResponseIsJson();$I->seeResponseContains('{'result':'ok'}');

Como puedes ver en el método amHttpAuthenticated comprobamos si estamos autenticados o no, forzando así el fallo. Podríamos incluso autenticarnos antes y así enganchar varios endpoints que, haciéndolo de forma manual, tendremos más difícil gestionar.

Te dejo con su documentación por si quieres seguir tirando del hilo.

¿Quieres aprender todo lo necesario para crear tu propia API y testearla?
Apúntante en el curso de diseño y tests de APIs con Postman, el único completo en castellano donde te explico todos los detalles de esta herrmienta.

Crear un cliente para consumir la API desde nuestro código ¶

Parece una tontería, pero piensa en cuántos tutoriales de conexión a una API has visto que separen la responsabilidad de comunicación entre plataformas del resto de la lógica. Ya te digo yo que pocos.

Hay que intentar rebuscar en nuestros conocimientos o, si es más fácil, en GitHub. Así encontraremos soluciones de librerías hechas concretamente para conectarse a una API y envolver esa funcionalidad en una interfaz propia. Podremos disfrutar de una serie de métodos que esconden para el resto del código las tripas de la conexión (autenticación, sesiones, estados…).

Un par de ejemplos:

• El cliente de node para conectarse a la API de recombee (un sistema de recomendaciones).
• El cliente de PHP para conectarse a la API de CKan (un gestor open source de datos abiertos).

Da igual si te suenan a chino ambas API’s. Casi mejor si vas a ver el código. Encontrarías cosas así:

$Ckan = new CkanClient($apiUrl, $apiKey);$ckanResults = $Ckan->package_search('organization:irs-gov');

Aquí no nos vamos a preocupar de gestionar la autenticación del usuario, solo queremos los resultados que cumplan la condición de package_search. Además los parámetros de CkanClient podrían ser valores de entorno, incluso no conocerlos directamente. Mucho más limpio, sin duda.

Seguro que encuentras ejemplos en tu lenguaje de programación favorito.