API Interacciones básicas

Introducción

La creación de metadatos en Anjana tiene un ciclo de vida específico por los canales habituales (Web App, API). Dicho ciclo consiste en la generación de un objeto con estado DRAFT (o IMPORTED si se ha realizado importando los datos con metadato automático desde TOT), pasado a PENDING mientras el workflow de validación está en proceso hasta su aprobación final, o rechazo.

Swagger

Este documento presenta distintas operaciones que se pueden realizar para seguir el ciclo propuesto por Anjana y que se presentan en una API. Para información más técnica o necesaria para realizar la llamada, consultar el endpoint en https://wiki.anjanadata.com/es/integraciones/26.1/kerno-api

En cada endpoint o grupo de endpoints se especifica a qué módulo corresponden, que será el módulo que visitar en Swagger para ver los detalles.

Además, se incluyen instrucciones y ejemplos del mecanismo a emplear para introducir en Anjana metadato que no va a seguir ese ciclo estándar, además de poder obtener listados filtrados del metadato presente.

Herramientas

Al ser simples APIs cualquier herramienta capaz de hacer una petición REST es válida.

En este documento, en los casos que incluyen alguna captura o en los que se especifica alguna acción en las llamadas REST, se utiliza la herramienta de Postman.

Multilenguaje

Para las peticiones que traten algún texto con multilenguaje o traducciones (recuperar el metadata de un objeto, búsqueda de SolR, etc) se puede especificar en qué idioma se quiere se devuelva la información (el caso más claro es obtener el metadato de un objeto con sus valores con la traducciones en un idioma en particular).

Para ello es necesario incluir la cabecera “x-language”, introduciendo un valor que coincida con uno de los códigos i18n que haya configurados en la aplicación. Como se puede ver en el siguiente ejemplo:

Añadir que la cabecera es totalmente opcional, y si no se recibe se devolverán los resultados en el idioma del usuario con el que se realiza la petición o, si no existe, en el idioma por defecto de la aplicación.

SSL

Anjana tiene securizada su API, como toda su interfaz, bajo certificados firmados por entidades certificadoras públicas reconocidas (Let's Encrypt, DigiCert, etc. Ver https://wiki.anjanadata.com/es/seguridad/26.1/mecanica-de-certificados .

Al tratarse de certificados de una CA pública, cualquier cliente HTTP (curl, Postman, código) confía en ellos por defecto, sin necesidad de indicar ningún certificado adicional.

Solo en entornos con un certificado autofirmado o emitido por una CA privada (por ejemplo, algunos despliegues On-Premise/IaaS ) es necesario indicar explícitamente la CA de confianza:

curl --cacert my-ca.crt https://{url_request}

Sólo para pruebas y desarrollo se puede utilizar la desactivación de la verificación SSL en cUrl con la opción -k, ya que esto iimplica una conexión sin validación de seguridad.

Glosario

En todas las url se van a incluir variables que se tendrán que modificar en el momento de ejecutar la llamada. A continuación se incluye una explicación de qué se tiene que poner en cada una.

• host: es la IP o alias donde está desplegado Anjana (ex: google.com)

• provider: el proveedor de gestión de identidades que se quiere utilizar, con el nombre que esté configurado en el yml de zeus (ex: azure)

• objectType: el tipo del objeto involucrado en la petición (ex: ENTITY)

• objectSubType: el subtipo del objeto involucrado en la petición (ex: DATASET)

• idObject: el id del objeto involucrado en la petición (ex: 21)

• state: el estado del objeto involucrado en la petición (ex: APPROVED)

• workflow: tipo de workflow (ex: CREATE).

• target: la colección de solr en la que indexar (ex: KERNO).

Minio/S3

Introducción

Para la gestión de ficheros como metadato (UPLOAD_FILE y ARRAY_UPLOAD_FILE) Anjana usa Minio o S3 para almacenar los ficheros.

Instalación y uso

Se requiere la instalación de un cliente de MinIO para interactuar directamente con el S3 interno sin pasar por el portal de Anjana.

Para usar el cliente MinIO se tiene que instalar de la siguiente manera:

wget https://dl.min.io/client/mc/release/linux-amd64/mc

después darle permisos de ejecución

chmod +x mc

y establecer la conexión con el servidor

./mc alias set minio https://{{host}}:9000 {{user}} {{password}} --api S3v4

para finalmente copiar el fichero al bucket que corresponda

./mc cp xxxxx.pdf minio/dsa

Login

Obtención de token

Antes de poder realizar cualquier operación en las APIs es necesario disponer de un token de acceso. Dicho token se recoge al loguearse.

Según el gestor de identidades que se esté utilizando existen distintos endpoints para obtener el token.

Todos estos endpoint se encuentran en el módulo de Zeus.

El payload a enviar en todos los casos será el siguiente:

{
  “u”: “usuario”,
  “p”: “contraseña”
}

Donde tanto “u” como “p” deben estar codificados en base64.

LDAP

Consiste en una llamada

POST https://{{host}}/gateway/public/v4/auth/login/ldap

Este endpoint se conecta al ldap correspondiente usando las credenciales enviadas y devuelve el token necesario para el resto de llamadas, junto con información del usuario y sus permisos (que varían según el estado de la licencia).

Base de datos

Consiste en una llamada

POST https://{{host}}/gateway/public/v4/auth/login/local

Este endpoint se conecta a la BD de zeus usando las credenciales enviadas y devuelve el token necesario para el resto de llamadas, junto con información del usuario y sus permisos (que varían según el estado de la licencia).

Saml 2.0

Consiste en una llamada

GET https://{{host}}/gateway/public/v6/auth/saml2/login

Este endpoint sirve para que una vez se haya conectado con SAML usando las credenciales correspondientes, devuelve el token de Anjana necesario para el resto de llamadas, junto con información del usuario y sus permisos (que varían según el estado de la licencia).

Resto de providers

Consiste en una llamada

GET https://{{host}}/gateway/public/v6/auth/oidc/login

Este endpoint sirve para que una vez se haya conectado con el proveedor que se haya especificado de zeus usando las credenciales correspondientes, devuelve el token necesario para el resto de llamadas, junto con información del usuario y sus permisos (que varían según el estado de la licencia).

Envío del token

Con el token obtenido en alguno de los endpoints previamente definidos se debe incluir en cualquier petición en la cabecera .

Ejemplo desde POSTMAN:

Ejemplo desde código:

headers.add("Authorization", "Bearer " + token);

Códigos de respuesta de la API según el estado de la licencia