Una API o interfície de programació d’aplicacions és un conjunt de mètodes per recuperar dades perquè puguin ser processades per altres aplicacions.

REST és una arquitectura de software per a sistemes hipermedia. Actualment REST és el terme que s'utilitza per descriure tota interfície entre sistemes que utilitzi el protocol HTTP per a determinar operacions a ser executades sobre un conjunt de dades o directament obtenirles, formatades i sense les complicacions pròpies de realitzar aquesta tasca a un nivell més directe.

Un cop es coneix l’estructura de les dades, només cal cridar els mètodes corresponents, tenint en compte que es poden combinar els mètodes entre si.

A nivell general utilitzem els següents conceptes:

Tipus de contingut: Definim un tipus de contingut concret a partir d'un nombre arbitrari de camps, grups i relacions. Exemple: El tipus de contingut “acte”, tindria tots els camps relatius a un acte (títol, localització, data d'inici i finalització, etc.).

Dataset: Definim un dataset com un conjunt de dades d'un tipus de contingut concret; per exemple, l'agenda d'actes de les biblioteques. Un dataset és un subconjunt del tipus de contingut. Exemple: el dataset “Agenda de museus” i el dataset "Agenda de les biblioteques" tenen dades del tipus de contingut “acte”.

Relació: Les relacions ens permeten connectar dades d'un tipus de contingut amb un dataset concret o un altre tipus de contingut. Per exemple, podem definir un dataset que sigui la llista de municipis i un tipus de contingut per a actes, podent relacionar totes dues dades a partir d'un identificador únic (codi INE). La gràcia de tenir les dades relacionades és que al recuperar la informació, també és possible recuperar les dades relacionades dins de la mateixa crida. La relacions es poden fer entre tipus de continguts o entre tipus de contingut i dataset (que no és altre cosa que un sub-conjunt de dades del tipus de contingut). Exemple: El tipus de contingut “recinte” estan relacionats amb el tipus de contingut “municipi” a través del codi INE, llavors, quan recuperéssem un recinte, també recuperem la informació del municipi on està ubicat.

Grup: Un grup és un conjunt o agrupació de camps.

Camp: Els camps defineixen els diferents valors que pot tenir un tipus de contingut. Els camps tenen diferents propietats:

Nom: Una etiqueta per referenciar el camp.

Nom màquina: Nom per identificar el camp en l'interacció amb la API. 

Pes: Valor que s'utilitza per ordenar els camps dins d'un registre.

Primari: Indica que aquest camp identifica el registre del que forma part, per tant, també té un valor únic dins el mateix dataset.

Multivaluat: Indica que el camp pot pendre més d'un valor.

Obligatori: Indica que en tot registre del dataset aquest camp ha de tenir un valor assignat.

Únic: Indica que el valor del camp no es pot repetir en la resta de registres d'un mateix dataset.

Tipus: Indica com està definit el valor del camp. Pot ser: booleà, data, decimal. email, enter, geolocalització, text, text llarg o url.

L'API només és de consulta, via REST i utilitza URLs “netes” per a les crides. Per tant, no hi ha paràmetres GET, sinó que en el seu lloc utilitza un sistema de parelles de paràmetre i valor.

La ruta és: http://do.diba.cat/api/_CRIDA_

On _CRIDA_ te la forma parametre1/valor1/parametre2/valor2/ ... /parametreN/valorN

Totes les dades són accessibles en format CSV, XML, RDF-XML i JSON (per defecte). Els resultats en format XML, RDF-XML i JSON contindran l'estructura interna de camps i grups que s'ha definit; en canvi, el format CSV per la seva naturalesa només permet els valors dels camps de forma lineal sense estructura. Per als camps multiavaluats en format CSV, s'utilitza un caràcter separador “;” per separar els diferents valors dins d'un mateix camp: “valor1_camp1”,”valor1_camp2;valor2_camp2;valor3_camp2”,”valor1_camp3”...

No importa l'ordre en què es cridin els parells. Si els paràmetres tenen un valor per defecte i no incloem a la ruta el valor d’un paràmetre que és obligatori, aquest prendrà el valor per defecte.

Un concepte clau que està definit en tots els tipus de continguts, datasets i camps és el machine_name o nom-màquina. Es tracta d’un valor preparat especialment perquè l’utilitzi el software i les màquines, que no canvia mai i que no conté cap caràcter especial, ni espais en blanc i es limita al subconjunt de caràcters ASCII-96. Aquest valor s’utilitza com a identificador i és ideal per utilitzar en totes les crides independentment del joc de caràcters utilitzat, perquè el subconjunt ASCII-96 és comú en tots els jocs de caràcters; per tant, sempre que sigui possible s’ha de treballar amb el machine_name.

Quadre resum de crides disponibles

L'API de dades obertes consta de diferents tipus de camps i cada camp pot tenir diferents propietats:

A l'apartat recuperació de la informació dels camps i l'estructura pots veure com consultar els tipus dels camps d'un dataset i les seves propietats.

Alguns tipus de camps permeten tipat, això ens permet indicar que el filtre, la comparació o l'ordenació que estem indicant s'ha de fer utilitzant una conversió de format concreta enlloc de fer-ho per text.

Per exemple, si volem recuperar  tots els actes posteriors al 23/06/2016 podem indicar-li que per fer la comparació utilitzi una data i ignori la hora amb el tipat ":date": camp-[field]-greater/date:2016-06-23, o si volem els actes entre les 9h del matí i les 17h de la tarda podem utilitzar el tipat ":datetime" perquè tingui en compte els hores i utilitzar dos filtres: camp-[field]-greaterequal/datetime:2016-06-23_09:00:00/camp-[field]-loweerequal/datetime:2016-06-23_17:00:00

Tipats disponibles:

• date: YYYY-MM-DD
• datetime: YYYY-MM-DD_hh:mm:ss

Els valors màgics són variables reservades que defineix el sistema, i que permet, per exemple recuperar les activitats del dia amb una URL estàtica sense haver-li de passar el dia actual podent inscrutar dades en webs estàtiques a tarvés de widgets.

Valors màgics disponibles

• date:now (dia actual)
• datetime:now (dia i hora actuals)

Exemples:

Llista d'actes que comencen avui: https://do.diba.cat/api/tipus/acte/camp-data_inici/date:now

No es necessita cap token per utilitzar l'API de dades obertes i per consultar qualsevol dada de datasets públics.

Els tokens són seqüències de valors alfanumèrics que es poden afegir a les crides de l'API i que s'utilitzen amb propòstis estadístics i per donar accés a datasets privats.

Els tokens els facilita la Diputació de Barcelona i aquests poden ser variables en funció d'un algoritme que fa que el token vagi canviant segons una clau pública i privada o poden ser estàtics i no canviar mai.

Hi ha tres mètodes diferents per fer una crida amb token:

• A través dels HEADERS de la crida HTTP (variable diba-token)
• A través del mètode POST (variable token)
• A través del mètode GET (_CRIDA_API_/token/{valor})

Per motius de seguretat es recomana utilitzar preferentment pels tokens HEADERS o POST i crides HTTPS sempre, i en últim terme GET i HTTP si només s'utiliza el token per motius estadístics i no es pot implementar per POST o HEADER.

Exemple PHP/cURL

Token via HEADER

$ch = curl_init($crida);
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['diba-token: ' . $token],
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Token via POST

$ch = curl_init($crida);
curl_setopt_array($ch, [
  CURLOPT_POSTFIELDS => ['token' => $token],
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Token via GET

$ch = curl_init($crida . '/token/' . $token);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);

Finalment, cal tenir en compte que els criteris i paràmetres són combinables entre ells, tot i que s’ha d’entendre que la combinació pot no retornar resultats.

Exemple: https://do.diba.cat/api/dataset/municipis/geord-camp/localitzacio/geord-cord/41.5606948,1.523511/pag-ini/1/pag-fi/10

Aquesta crida ens tornarà les dades del municipis i ens tornarà els primers 10 resultats ordenats per proximitat a la coordenada 41.5606948,1.523511 que s’ha indicat.

Exemples diversos:

Llista dels conjunts de dades disponibles:
https://do.diba.cat/api/info/datasets

Llista dels tipus de continguts disponibles:
https://do.diba.cat/api/info/tipus

Llista de temes o àmbits temàtics d'actuació de la Diputació de Barcelona:
https://do.diba.cat/api/dataset/temes

Llista de municipis de la província de Barcelona:
https://do.diba.cat/api/dataset/municipis

Llista dels municipis de la província de Barcelona en format XML:
https://do.diba.cat/api/dataset/municipis/format/xml

Llista d'actes de la cartellera dels espais escènics municipals:
https://do.diba.cat/api/dataset/escenari

Tots els punts d'interès de qualsevol conjunt de dades:
https://do.diba.cat/api/tipus/punt

Tots els actes de qualsevol conjunt de dades:
https://do.diba.cat/api/tipus/acte/pag-fi/100

Els 10 punts d'interès més propers a Santa Coloma de Gramenet (41.453889,2.211111):
https://do.diba.cat/api/tipus/punt/geord-camp/localitzacio/geord-cord/41.453889,2.211111/pag-ini/1/pag-fi/10

Registres modificats avui en el dataset de biblioteques:
https://do.diba.cat/api/dataset/biblioteques/camp-_lastChange/date:now

Registres modificats amb data igual o superior a l’1 de febrer de 2015 a les 15:00h en el dataset municipis:
https://do.diba.cat/api/dataset/biblioteques/camp-_lastChange-greaterequal/datetime:2015-02-01_15:00:00

Biblioteques a 1000 metres de distància de la coordenada 41.37,2.18:
https://do.diba.cat/api/dataset/biblioteques/format/json2/ubicacio/41.37,2.18/geocamp/localitzacio/radi/1000

L'API té un sistema de memòria cau per millorar el rendiment que evita haver de processar les mateixes consultes de forma repetitiva. Per tant, quan es fa una crida a l'API aquesta s'enmagatzema en una memòria cau del servidor i, si se li torna a demanar la mateixa petició exacta, torna la resposta emmagatzemada directament de la memòria cau.

Aquesta memòria cau s'anomena APICache i té una persistència de 12 hores, així que tota crida realitzada de forma repetitiva es manté invariable durant almenys 12 hores, encara que durant aquest interval hi hagi hagut una modificació de les dades. Quan es modifica una dada l'API pot trigar de 0 a 12 hores a servir la modificació.

Per saber si les dades que estàs consumint s'han generat en aquell moment o han estat servides directament per la memòria cau, les respostes incorporen una propietat anomenada cache al final de totes les respostes. Aquesta propietat indica el dia i hora exactes en què es va guardar aquella resposta en memòria cau. Si les dades no incorporen aquesta propietat, és perquè la resposta s'ha generat en aquell precís moment i, per tant, no s'han servit de l'APICache.

Exemple: cache:"2017-06-07 03:13:19"

La data i hora estan en temps universal UTM.

Per tant, a la freqüència d'actualització de les dades que indiquen els datasets cal afegir-hi un marge adicional de 12 hores, que és el temps màxim que pot trigar a propagar-se el canvi a través de la memòria cau de l'API.

1.11 Lepista - 02/06/2017

• Suport de crides amb JSONP: format/json?callback=jsonParser
• Bugfixing, millores de rendiment i millores en la visualització i la navegació.
• Noves opcions en la incrustació externa de visors: Mostra el botó per incrustar

1.10 Kretzschmaria - 06/03/2017

• Millores en les gràfiques d'estadístiques d'ús públiques.
• Caixes d'informació adicional en els visors: estadístiques d'ús del dataset, exemples de crides de l'API i enllaços ràpids a la documentació.
• Millores importants de rendiment.
• Millores en la visualització dels filtres dels visors.
• Millores en la visualització del visor tipus Mapa.
• Incorporació d'informació sobre els camps dels datasets i la seva descripció en els visors.

1.9 Junghuhnia - 18/01/2017

• Afegides les estadístiques per visors a les estadístiques: https://do.diba.cat/stats/
• Nou filtre dinàmic per columna en els visors tipus taula dels datasets.
• Nova sortida RDF-XML: format/rdf-xml.
• Noves opcions per a seleccionar el tipus d'agregació en el visor mapa.
• Nova opció d'exportació de totes les dades en format XML-RDF.

1.8 Inocybe - 05/09/2016

• Pàgina pública d'estadístiques d'ús de l'API: https://do.diba.cat/stats/
• Pàgina d'informació municipal per agrupar totes les dades obertes relacionades amb cada municipi: https://do.diba.cat/municipis/
• Actualització de la maquetació responsiva.

1.7 Helvella - 02/08/2016

• Nou visor de dades: Calendari.

1.6 Gírgola - 15/07/2016

• CANVI A L'API: Eliminem el doble format de sortida format/json i format/json2, en un únic format de sortida simplificada json. Ara els tres formats de sortida disponibles són: json, xml i csv, en cas de no especificar-se o indicar un format de sortida incorrecte tornarà la sortida json.
• Els datasets incorporen més metadades a la sortida com: paraules clau, freqüència d'actualització, llicència, sector, tema, responsable de les dades i referències. Exemple: http://do.diba.cat/api/info/datasets
• Nou camp cache: "YYYY-MM-DD HH:MM:SS". El camp indica el dia i hora en que es va guardar la resposta a la memòria cau del sistema. Si el camp no existeix és perquè s'ha servit la dada directament de base de dades, si existeix indica quan es va guardar la resposta a la memòria cau. La vida màxima de la memòria cau és de 24 hores.

1.5 Fredolic - 23/05/2016

• Visor de dades en format mapa: https://do.diba.cat/data/
• Possiblitat de cerca per text lliure en tots els camps: camp-all/text o camp-all-like/text.
• L'operador like s'ha fet case insensitive.
• Datasets multilingües: es pot filtrar per codi d'idioma i recuperar un mateix dataset en tots els diferents idiomes disponibles, exemple: api/dataset/parcsequipaments/idioma/es, api/dataset/parcsequipaments/idioma/ca.
• Generació d'un codi d'incrustació en els visors de dades per a webs externes via iframe.
• L'exportació de dades a XML, JSON o CSV quan estàs en un visor respecta els filtres i l'ordenació triada.
• S'ha afegit una capçalera crossdomain a l'API per permetre crides AJAX externes.
• La incrustació incorpora via iframe el botó d'exportació de dades.

1.4 Escarlet - 16/07/2015

• Visor de dades en format taula: https://do.diba.cat/data/
• Visor de dades per tipus de contingut.
• Visor de dades per conjunt de dades.
• Filtres en el visor de dades per camp, municipi o tema.
• Exportació de les dades filtrades en el visor en els formats: CSV, JSON i XML.
• Nova crida de l'API per agregar contingut per a consultes tipus GROUP BY: agrega/machinename. Es permet agregar per mútilples camps i la resta de filters són aplicables (flitres, formats o paginació). Per exemple, recompte de càrrecs electes per sexe i municipi (codi INE): api/dataset/electes/agrega/codi_ine/agrega/sexe.

1.3 Dent de rata - 21/05/2015

• Nou camp a la sortida de tots els elements: "_lastChange", amb la data de creació o darrera modificació del registre.
• Es poden recuperar, ordenar i filtrar dades per data de modificació del registre, per exemple: camp-_lastChange-greaterequal/date:2015-05-21.

1.2 Camagroc - 10/12/2014

• Nou identificar únic universal per a qualsevol entitat: _id
• A partir d'ara la paginació comença per 1 enlloc de per 0: pag-ini/1 (si es passa un 0 es considerarà un 1)
• S'ha modificat el funcionament de la cerca LIKE amb camps multivaluats, ara evalua la condició valor a valor enlloc d'evaluar tot el string de valors.
• Sistema de tokens i credencials per poder modular recursos (thresholding) i accesos.
• DEPRECAT: Nova sortida JSON amb estructura simplificada format/json2 (en una futura versió aquesta serà la sortida per defecte format/json).
• Eliminats els salts de línea innecesaris de la sortida en XML: format/xml
• Millora del rendiment quan es filtra per dataset o tipus de contingut: dataset/machinename i tipus/machinename
• Millora del rendiment quan es filtra o s'ordena per proximitat: geord-camp/localitzacio/geord-cord/41.453889,2.211111

1.1 Bec de perdiu - 21/07/2014

• S'incorpora l'operador OR a les crides de paràmetres: camp-machinename/valor1||valor2
• S'incorpora l'operador AND a les crides de paràmetres: camp-machinename/valor1++valor2
• S'incorpora l'operador OR NULL a les crides de l'API: camp-machinename-ornull/valor
• S'extenen les relacions entre conjunts de dades i ara poden ser de dos tipus ContentType/Dataset o ContentType/ContentType.
• Les respostes amb relacions entre conjunts de dades no incrustades, al ser de 1 a N, incorporen un contador per evitar que l'aplicació hagi de fer una segona crida per mirar quants registres compleixen la relació.
• CANVI A L'API: Es canvia el format de les dates per YYYY-MM-DD, tant a les crides com a la sortida per facilitar l'ordenació i millorar el rendiment (abans era DD-MM-YYYY).
• S'afegeix el tipat date a les crides: camp-machinename/date:2014-10-27
• S'afegeix el tipat datetime a les crides: camp-machinename/datetime:2014-10-27_09:00:00
• CANVI A L'API: Quan es filtra o s'ordena per data s'ha d'especificar obligatòriament el tipat a la crida: camp-machinename/date:2014-11-21
• S'afegeix la variable 'now' per a les crides amb dates, cosa que et permet fer crides tipus: camp-data_inici-greaterequal/datetime:now
• CANVI A L'API: Es simplifica la sintaxis de la crida d'ordenació: ord-machinename/desc (abans era: ord-camp/machinename/ord-sentit/asc).

1.0 Apagallums

• Versió inicial de l'API REST.

Pets consultar exemples de codificació que utilitzen l'API de dades obertes perparats per a ser reutilitzats.

Exemples de codi

DKAN (la plataforma de gestió de dades de codi obert basada en Drupal, sobre la qual està construït aquest portal) ofereix una API per recuperar informació del catàleg de dades que normalment s'utilitza per sindicar continguts amb altres portals. L'APIs de DKAN es pot fer servir per recuperar metadades dels datasets.

L'API de DKAN és una API addicional i complementària a la nostra API de dades obertes.

Pots consultar més informació sobre les APIs de DKAN en aquest web.