API Rest privada

Coeli suporta una API segons l’estàndard Open Archives Initiative, especificat a https://www.openarchives.org/pmh/. El seu punt d’entrada seria:

GET o POST a /oai/1/$NOM_TENANT (on $NOM_TENANT ha de correspondre al nom de l’entorn de Coeli)

Aquest punt d’entrada de la API compleix amb el protocol OAI, estàndard que està abastament documentat amb la sintaxi i mètodes possibles. https://www.openarchives.org/pmh/

Coeli disposa d’una API basada en HTTP i JSON que segueix l’estil REST. Els seus trets característics són:

• Completa: el 100% de les funcionalitats disponibles als usuaris finals són també disponibles a l’API per a qui tingui els permisos de seguretat necessaris, ja que l’aplicació HTML de backoffice s’ha programat contra aquesta mateixa API.
• Segura: comunicacions encriptades sota HTTPS, autenticació basada en token de seguretat que és cancel·lable en qualsevol moment (deshabilitant de forma immediata l’accés a l’API a qui s’hagi facilitat aquell token).
• Simple i basada en estàndards amplament acceptats: ús correcte d’HTTP (mètodes, URIs, capçaleres, codis de retorn, etc) i format JSON per a peticions i respostes.

L’API de Coeli segueix els estàndard web HTTP i JSON. En particular:

• Es fa un ús adequat de l’estàndard URL, usant correctament l’esquema, el path i la query.
• Es fa un ús adequat dels estàndards HTTP, usant correctament els mètodes de petició (i respectant la seva idempotència), les capçaleres de petició, el cos de la petició i els status code, capçaleres i cos en les respostes.
• Es fa servir el format JSON per simplicitat i llegibilitat per part d’humans.

L’API de Coeli és basa en l’estil REST. En particular:

• Cada recurs s’identifica per una URL i s’ha dissenyat amb cura la jerarquia d’URLs per a que tingui sentit. Per exemple, la URL del recurs que representa el conjunt dels objectes patrimonials seria https://app.coeli.cat/NOM_TENANT/HeritageObject, mentre que la d’un objecte patrimonial concret és, per exemple:

https://app.coeli.cat/NOM_TENANT/HeritageObject/H296965

• Es respecta la semàntica dels mètodes de petició de HTTP.
• S’intenta evitar l’existència de URLs que només són mètodes, sinó que les operacions es fan fent servir URLs que representen recursos.
• Com a única excepció, la representació alternativa en formats rdf o jsonld s’ha considerat un subrecurs (per exemple GET /$entitat/$id/rdf) enlloc d’una capçalera per a facilitar l’ús de l’API als desenvolupadors.

CoeliSync es una eina que facilita la sincronització amb altres sistemes. Els administradors (o usuaris avançats) poden utilitzar  aquesta eina, ja sigui connectant directament al teu sistema a través de crides SQL o mitjançant el processament de lots d’ingesta a través de fitxers. També sincronitza totes les imatges i els documents (informes,…) vinculades que tinguis al teu sistema de fitxers.

D’altra banda es poden configurar processos ETL (Extract, Transform and Load) per importació de dades en altres formats, com per exemple XML, MAC21 ISO2709,…

El model de la informació de Coeli està basat en una sèrie de conceptes que val la pena precisar abans de parlar de la funcionalitat de les seves APIs.

• Tota la informació s’estructura en fitxes. Cada fitxa té un identificador únic de recurs (URI) que permet fer-hi referència i consultar-ne la informació mitjançant la API i un identificador intern anomenat idInSource.
• Cada fitxa correspon a un determinat tipus d’entitat. Així, per exemple, els objectes patrimonials tenen fitxes de tipus ‘HeritageObject’, les col·leccions tenen fitxes de tipus ‘Collection’ i les persones i entitats tenen fitxes de tipus ‘Actor’.
• La URI d’una fitxa està formada per https://app.coeli.cat/$NOM_TENANT/$entitat/$idIntern i és també la URL per a consultar el detall de la fitxa. L’identificador intern d’una fitxa, per tant, ha de ser únic entre les fitxes d’un mateix tipus d’entitat.
• El tipus d’entitat d’una fitxa determina quines propietats tindrà la fitxa, quines seran obligatòries, quines seran multi-valor, etc. Tota aquesta informació (que anomenem model de la informació) també es pot consultar per la API.
• Les fitxes són representades per l’API en forma d’objectes JSON. Una mateixa fitxa pot tenir diverses representacions segons quins siguin els permisos de l’usuari que fa la consulta.
• Una fitxa pot fer referència a altres fitxes. Per exemple, en consultar la fitxa d’un objecte patrimonial, trobarem, entre altres, referències a l’ens dipositari, als creadors de l’objecte, a la font d’ingrés…
• Cada referència es representa al json mitjançant un objecte JSON que té un atribut que conté la URI de la fitxa referenciada. Aquest objecte pot contenir, a més, atributs de la fitxa referenciada que s’inclouen per evitar haver de fer consultes addicionals quan només es necessita certa informació. Per exemple, cada referència a un dels creadors d’un objecte inclou, al JSON retornat per la consulta de l’objecte, el nom del creador i la seva data i lloc de naixement i defunció en cas que hi siguin; d’aquesta manera una aplicació que hagués fet aqueta petició no necessitaria una segona petició per a obtenir el nom i demés informació sobre els creadors de la peça consultada.

Aquest model de la informació i el seu meta-model donen una coherència a tota l’API que la fa molt usable. Així, per exemple, l’API de cerca és exactament la mateixa per a buscar objectes que per a buscar persones o entitats. L’únic que canvia són quins atributs podem fer servir als criteris de cerca i quin és el format dels objectes JSON retornats per a cada un dels resultats obtinguts.

A continuació es descriuen breument les diverses peticions que suporta l’API de Coeli. Hem seguit les següents convencions:

• A totes les URLs aquí presentades (excepte a les d’OAI) cal afegir-los davant el nom de servidor (hostname) i el nom de tenat de la instal·lació.
• Una paraula precedida de $ indica un paràmetre de la URL

Per exemple, quan mencionem la petició GET /$entitat/$id ens referim a URLs com ara https://app.coeli.cat/$NOM_TENANT/HeritageObject/H646425, on $entitat té el valor “HeritageObject” perquè volem consultar la fitxa d’un objecte patrimonial i $id té el valor H646425 perquè aquest és l’identificador de la fitxa que volem consultar. $NOM_TENANT correspon al nom específic de l’entorn de Coeli per a cada client.

GET /$entitat/slugs/$slug: Retorna una fitxa a partir del seu slug. Un slug és un identificador fàcil de llegir per als humans però que pot canviar al llarg de la vida d’una fitxa.

GET /$entitat/$id: Retorna una fitxa a partir del seu identificador intern.

GET /$entitat/$id/(rdf|jsonld): Retorna una fitxa en format rdf o jsonld.

GET /$entitat/$id/history: Retorna un llistat històric de canvis a una fitxa. Per a cada canvi indica qui el va fer, en quina data i quins canvis hi va fer. La informació es pot demanar resumida amb el paràmetre ?summarized.

GET /$entitat/$id/$propietat: Retorna la imatge corresponent a la propietat $propietat de la fitxa identificada a la URL. Permet accedir directament a una propietat de tipus imatge sense haver de consultar prèviament la fitxa per a obtenir la URL de la imatge.

Com ja s’ha mencionat, Coeli permet consultar el model de dades. Aquest és un model de les dades que permet que els clients de l’API puguin descobrir dinàmicament quines propietats té cada tipus d’entitat i, així, puguin construir cerques de forma dinàmica. Com a mostra del que és possible, tota l’aplicació HTML de backoffice ha estat construïda de forma dinàmica, de tal manera que descobreix l’esquema de dades i construeix els llistats, formularis, formularis de cerca i demés pantalles en funció d’aquest.

GET /: Retorna el model de dades. Aquest està expressat en JSON en un llenguatge de meta-modelat.

Coeli disposa d’un potent motor de cerques basat en tecnològica Elasticsearch que permet una funcionalitat avançada de cerca que, com totes, està disponible tan a usuaris finals com a l’API. Algunes de les característiques d’aquest motor de cerques són:

• Possibilitat de fer cerques per un conjunt de criteris complexes. Es poden indicar diverses condicions que es combinaran amb l’operador booleà OR (es retornaran fitxes que satisfacin algunes de les condicions). Cada condició pot ser un criteri complex format per diversos criteris senzills combinats amb l’operador AND (tots els criteris senzills s’han de satisfer).
• Paginació dels resultats de la cerca: Cada cerca retorna el nombre total de resultats disponibles i permet demanar resultats d’una pàgina concreta de resultats (per exemple, 20 resultats a partir del resultat número 30).
• Facetat dels resultats de la cerca: Amb els resultats de la cerca es retornen un conjunt de facetes indicant, per a cada ella, quantes de les fitxes trobades per la cerca tenen cada valor facetat. Per exemple, una cerca de fitxes d’objecte patrimonial que continguin el text “Picasso” podria retornar una pàgina de 20 resultats d’un total de 4000 fitxes trobades; entre les facetes dels objectes patrimonials, hi ha el creador de l’objecte i la cerca ens podria retornar, per exemple, que 3950 de les fitxes retornades tenen per un dels creadors a Pablo Picasso.

Cada criteri simple està format per una propietat, un operador i un valor. Les combinacions possibles són:

• Per a tot tipus de propietats:
  • Cerca fitxes que tenen o no la propietat informada (valors cert o fals)
• Per a propietats de tipus data o data/hora permet cercar valors…
  • en una data (de les 0:00 a les 24:00 de la data indicada)
  • entre dues dates
  • en un període (fitxa de tipus HistoricalPeriod o ChronologicalPeriod, per exemple, objectes creats als anys 80)
  • entre dos períodes
  • després d’una data, mes o any
  • abans d’una data, mes o any
  • de fa més de N dies indicats a la cerca (exemple, obres donades d’alta fa més de 30 dies)
  • de fa menys de N dies indicats a la cerca (exemple, obres donades d’alta fa menys de 30 dies)
• Per a propietats de tipus textual, permet cercar valors…
  • exactament iguals al text cercat
  • que contenen el text cercat
• Per a propietats de tipus referència a altres fitxes, permet cercar valors…
  • que contenen la referència indicada per la cerca o una de les seves referències filles (exemple, cercar objectes en que el nom de l’objecte pertany al nom d’objecte escultura, ja sigui una talla, un relleu, etc)
  • que es corresponen exactament amb la referència indicada (exemple, cercar objectes en que el nom de l’objecte és escultura, però no cap dels noms d’objecte fills d’escultura).
  • que referencien una fitxa que conté un cert text
• Per a altres tipus de propietats permet fer cerques pels criteris típics: per igualtat, o comparació (<, <=, <, >=) en el cas de propietats numèriques, per igualtat en el cas de booleanes, etc

GET /$entitat/: Retorna el llistat paginat sense filtrar de fitxes del tipus $entitat.

POST /$entitat/search/onestep: Realitza una cerca i en retorna els resultats. Es tracta d’una petició POST perquè els criteris de la cerca, que poden ser complexos, s’indiquen en JSON al cos de la petició.

Coeli permet desar cerques per a poder cercar directament per un identificador de cerca, sense haver d’incloure cada vegada tots els criteris de la cerca:

GET /search/: Retorna la llista de cerques desades

GET  /$entitat/search/: Retorna la llista de cerques desades de l’entitat

GET /$entitat/search/$id: Retorna els resultats de la cerca. Admet els paràmetres offset, limit, facet

POST /$entitat/search: Crea una nova cerca i en retorna l’identificador. Els criteris s’indiquen al cos de la petició en el mateix format que per a la cerca /$entitat/search/onestep.

PUT /$entitat/search/$id: Crea o actualitza una cerca de la que disposem de l’identificador.

DELETE /search/$id: Esborra una cerca

GET /user: Consulta la llista d’usuaris disponibles

DELETE /users/$id: Dóna de baixa un usuari

PUT /users/$id: Canvia el rol de seguretat de l’usuari $id

POST /invitations: Convida un o més usuaris a partir del seu correu electrònic.

GET /roles: Consulta el rols de seguretat del token que fa la petició

GET /permissions: Consulta els permisos del token de seguretat que fa la petició

PUT /users/$email: Canvia la contrasenya de l’usuari identificat pel seu $email (que pot ser el propi usuari al que correspon el token de seguretat usat).

GET /import/progress: Consulta l’estat de les importacions en marxa. Per a cada entitat per a la qual s’estan important fitxes indica el nombre de fitxes importades i el total de fitxes que s’importaran.

GET /import/completed: Consulta les importacions finalitzades retornant si van finalitzar bé o amb error i quins van ser els errors en cas que n’hi hagin.

GET|POST|PUT /import/config: Permet gestionar la configuració de CoeliSync, l’eina de coeli que facilita la sincronització amb altres sistemes.

PUT /import/$id/archive: Arxiva una importació passant-la a considerar completada.

POST /import/$entitat(/$subPropietat): Inicia una importació CSV de dades d’una entitat o d’una propietat d’una entitat (per exemple per a importar un llistat de creadors dels objectes on cada fila es correspon a un dels creadors d’un dels objectes patrimonials).

GET /emptyObjects: Retorna la llista d’objectes buits. Aquests objectes es creen quan s’importa un objecte que en referencia un d’inexistent. No es considera error perquè és possible importar la informació d’aquests objectes a posteriori.

L’exportació de dades de Coeli permet exportar dades en format CSV o Excel. En ser processos potencialment llargs, primer cal crear una exportació i, després, un cop aquesta hagi finalitzat, es poden recollir els resultats.

POST /$entitat/actions/(ExportCSV|ExportExcel): Crea un treball d’exportació de dades (en format CSV o Excel segons la URL) a partir d’una cerca o d’un conjunt d’identificadors de fitxa. Veure “Accions massives”.

GET /export: Retorna l’estat de les exportacions no arxivades

GET /export/$id: Retorna el resultat de la importació $id incloent, en cas d’èxit, la URL per descarregar el fitxer CSV.

PUT /export/$id/archive: Arxiva la importació $id. Com que no es poden desarxivar, aquesta acció és equivalent a un esborrat lògic.

POST /$entitat: Crea una nova fitxa del tipus $entitat.

PUT /$entitat/$id: Modifica la fitxa $id del tipus $entitat.

PUT|POST /$entitat(/$id): Simula el procés de modificació o creació d’una nova fitxa del tipus $entitat. Útil per a validar les dades de la fitxa abans de crear-la o modificar-la i per a obtenir com quedarà la fitxa un cop s’hi afegeixi la informació que calcula Coeli a partir de les dades proporcionades. No modifica cap informació de forma persistent.

DELETE /$entitat/$id: Dóna de baixa una fitxa.

Coeli permet la creació de llistes de fitxes amb nom. Això permet a un usuari (de l’aplicació o de l’API) crear una llista amb nom i afegir-hi fitxes. Així pot treballar amb aquell conjunt de fitxes com cregui convenient. Cada llista de fitxes té un tipus d’entitat associat i s’hi identifica per un nom. A més, té una descripció i una marca conforme si és global (la poden veure i fer servir tots els usuaris) o no (només és visible per a l’usuari que la va crear).

GET /recordLists: Retorna la llista de llistes amb nom. Per a cada una indica el tipus d’entitat, el nom, la descripció i si és global o no.

PUT /$entitat/recordLists/id/update: Modifica el nom, descripció o marca de global d’una llista

DELETE /$entitat/recordLists/id: Esborra una llista

POST /$entitat/actions/(AddToList|RemoveFromList|SaveAsList): Veure “Accions massives”.

Coeli permet fer accions massives sobre un conjunt de fitxes. Totes les accions massives tenen una API coherent:

• Totes es fan mitjançant POST /$entitat/actions/$accio
• Totes es poden fer sobre un conjunt de fitxes seleccionades segons un dels 4 criteris següents, segons s’indiqui a la petició:
  • Conjunt d’identificadors proporcionats en la petició
  • Totes les fitxes del tipus de l’entitat
  • Totes les fitxes que es trobin fent una cerca senzilla amb el text indicat a la petició
  • Totes les fitxes que es trobin fent la cerca desada que s’indiqui a la petició

Els tipus d’accions disponibles són:

Update:  Fa una modificació massiva del conjunt de fitxes

ExportCSV, ExportExcel: Exporta el conjunt de fitxes en format CSV o Excel (veure “Exportació de dades”)

Publish, UnPublish: Publica o despublica el conjunt de fitxes

Delete: Esborra el conjunt de fitxes

SaveAsList: Desa el conjunt de fitxes en una nova llista amb nom (veure “Llistes de fitxes”)

AddToList: Afegeix el conjunt de fitxes a una llista amb nom existent (veure “Llistes de fitxes”)

RemoveFromList: Treu el conjunt de fitxes d’una llista amb nom (veure “Llistes de fitxes”)

AcceptAction: Dóna per vàlides les fitxes en el conjunt de fitxes