Requisitos
La API ainialab, ha sido desarrollada con el objetivo de conseguir un acceso rápido, fácil y seguro a las muestras y resultados que se generan en el entorno del lims. Para ello está provista de métodos que servirán a cualquier aplicación la extracción de los datos adecuados.
Está orientada por tanto a desarrolladores de software que necesiten integrar resultados de muestras analizadas en ainia a su propia base de datos de manera automatizada.
Ha sido elaborada usando la ideología de arquitectura REST con el traspaso de datos en formato JSON, se puede consultar una amplia introducción en la documentación de IBM.
Recursos
Los recursos disponibles son como los Objetos de un lenguaje de programación de alto nivel, pero los vamos a representar en notación JSON.
En la API ainialab tenemos varios recursos, entre ellos están las muestras y los resultados.
Serán los que figuren como métodos y soporten los verbos HTTP como PUT, GET, POST...
La URL base de la API es:
https://api-ainialab.ainia.es/api/
Si queremos consultar un recurso de primer nivel, como las muestras, la URL quedará así:
https://api-ainialab.ainia.es/api/<recurso>
Ahí cambiaremos <recurso> por el adecuado, como por ejemplo "samples" para las muestras.
Podemos ver un los recursos disponibles en la Referencia.
Autenticación
Para poder hacer uso de los recursos disponibles, primero debemos autenticarnos. Vamos a confiar en la tecnología JWT para generar un tokens de sesión.
Desde un terminal en GNU/Linux, debemos tener disponible la utilidad curl y sino es fácilmente instalable a través de los repositorios de la distribución que utilicemos.
Abrimos el terminal y tecleamos:
Reemplazando "prueba" por nuestro usuario y "test" por nuestra apikey.
Obtendremos una respuesta del estilo:
{
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MDM1OTk3MTgsImlhdCI6MTUwMzU5NjExOCwibmJmIjoxNTAzNTk2MTE4LCJzdWIiOiJ0ZXN0In0.G2GnN9NgvvmSKgRDGok0OjAyDWkG_qCn4FTxSfPUXDY"
}
Ese es nuestro token de sesión. Lo agregaremos a las cabeceras de todas las peticiones que hagamos para identificarnos de cara al servidor.
El tiempo de sesión está establecido en 5 minutos pasados los cuales hará falta volver a autenticarnos.
Vamos a exportar nuestra clave para poder utilizarla en las próximas llamadas a los recursos que hagamos
| code: | export ACCESS="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MDM..." |
|---|
Reemplazamos ahí por el valor jwt obtenido en el paso de la autenticación.
Ahora podemos probar que el servidor nos reconoce gracias al token y podemos obtener información de él.
Incluiremos en la llamada una cabecera llamada Authorization que incorporará nuestro token.
Si todo ha ido bien y el servidor nos reconoce, obtendremos algo así:
{
"msg": "Hello User"
}
Donde en vez de User deberá aparecer el nombre de nuestra empresa.
Paso de parámetros
Algunos de los recursos requieren que pasemos parámetros a la hora de ejecutar acciones, por ejemplo si queremos marcar una muestra como "Leída".
Vamos a ver ese ejemplo. Imaginemos que tenemos una muestra con ID = 1234 y queremos marcarla como leída para que no nos vuelva a aparecer la siguiente vez que listemos las muestras.
Haremos una llamada a la URI del recurso de la muestra pero con el método PUT y con parámetros JSON para indicar el valor.
Nos devolverá la representación JSON de la muestra tras la actualización, veremos que el campo de "leída" ha cambiado a true. Si ahora accedemos al recurso de las muestras para listarlas, veremos que esta ya no aparece.
Siempre podremos volver a marcarla como no leída (leida = false) en un futuro si sabemos su ID.