Interfície de programació d'aplicacions (API)

1.1. Anatomia de les peticions

Tota petició ha d'especificar obligatòriament un servei, la versió principal del servei, una operació vàlida per aquest servei i un format de resposta. Opcionalment, es poden especificar un seguit de paràmetres generals i específics del servei.

http://api.idescat.cat/{servei}/v{versió principal}/{operació}.{format}[?paràmetres]

Alguns serveis poden compartir la sintaxi de les peticions i l'estructura de les respostes. Aquests són tractats com un únic servei que disposa de subserveis. En aquest cas, la forma de la petició és:

http://api.idescat.cat/{servei}/v{versió principal}/{subservei}/{operació}.{format}[?paràmetres]

Tot i que aquesta és la forma en la qual internament són tractades totes les peticions, les APIs també solen admetre una sintaxi externa més amigable que no requereix especificar una operació (vegeu Invocació sense operació).

1.1.1. Servei i versió

Cada servei disposa d'un identificador, d'una versió i d'uns paràmetres específics. Per exemple, el servei d'Indicadors al dia s'identifica amb el valor indicadors i només disposa d'una versió (1).

Ex. 1: Petició a la versió 1 del servei d'Indicadors al dia

http://api.idescat.cat/indicadors/v1/{…}

Els serveis poden tenir diferents versions principals, incompatibles entre elles. Les millores incrementals no afecten la versió principal (per exemple, 1.01 respecte a 1.00) i, per tant, tampoc la petició.

1.1.2. Operació

Els serveis solen suportar una diversitat d'operacions. Per exemple, el servei indicadors admet l'operació dades, que retorna resultats estadístics, però també l'operació nodes.

Ex. 2: Dues peticions al mateix servei però a operacions diferents

http://api.idescat.cat/indicadors/v1/dades.{…}
http://api.idescat.cat/indicadors/v1/nodes.{…}

El servei i l'operació determinen l'estructura del document retornat.

1.1.3. Format

Determina el format de la resposta. Admet tres valors amb caràcter general:

• xml: retorna el resultat en format eXtensible Markup Language.
• json: retorna el resultat en format JavaScript Object Notation. Aquesta sortida reprodueix fidelment tota la informació que retorna la petició en format XML. Permet especificar una funció de devolució amb el paràmetre callback amb el nom de la funció. Tot i que JSON és una cadena codificada en UTF-8, per conveniència, la sortida en aquest format té en compte el valor especificat a enc.
• php: retorna el resultat en format PHP serialitzat. Aquesta sortida té la mateixa estructura que la sortida en format JSON: es tracta d'una cadena que pot ser desserialitzada per crear un objecte (no una matriu) PHP. En aquest cas, el resultat sempre es retorna codificat en UTF-8 amb independència del valor d'enc.

Ex. 3: Diverses peticions amb resposta en diferents formats

http://api.idescat.cat/indicadors/v1/dades.xml
http://api.idescat.cat/indicadors/v1/dades.php
http://api.idescat.cat/indicadors/v1/dades.json
http://api.idescat.cat/indicadors/v1/dades.json?callback=f

1.2. Paràmetres generals

Tota petició té uns paràmetres generals (comuns a tots els serveis) i uns paràmetres específics del servei, documentats a l'API del servei.

1.2.1. Idioma de la resposta (lang)

Admet tres valors:

• ca: català (valor per defecte)
• es: castellà
• en: anglès

Ex. 4: Resultat en castellà

http://api.idescat.cat/indicadors/v1/dades.xml?lang=es

1.2.2. Codificació de la resposta (enc)

Aquest paràmetre admet dos valors: utf-8 (valor per defecte) i iso-8859-1.

Ex. 5: Resultat codificat en ISO-8859-1

http://api.idescat.cat/indicadors/v1/dades.xml?enc=iso-8859-1

Si el format de la resposta és php la codificació és UTF-8, sigui quin sigui el valor d'enc.

1.3. Paràmetres específics

A més dels paràmetres generals descrits a l'apartat anterior, cada servei admet uns paràmetres específics ("variables") que permeten configurar la informació obtinguda. Aquests paràmetres estan documentats a l'API del servei.

Per exemple, l'operació dades del servei indicadors permet seleccionar el nombre d'indicadors obtinguts gràcies als paràmetres tt, max i min.

Ex. 6: Paràmetres específics

http://api.idescat.cat/indicadors/v1/dades.xml?tt=10&max=10&min=3

1.3.1. El paràmetre general p

Les variables del servei (o "paràmetres específics") poden encapsular-se en un paràmetre general per efectuar una crida més compacta. Per fer-ho cal incloure un seguit de parelles variable/valor separades per punts i coma.

Ex. 7: Peticions sinònimes

http://api.idescat.cat/indicadors/v1/dades.json?tt=10&max=10&min=3
http://api.idescat.cat/indicadors/v1/dades.json?p=tt/10;max/10;min/3

1.4. Invocació sense operació

Per raons d'amigabilitat, algunes APIs poden admetre peticions amb una sintaxi que no requereix especificar una de les operacions generals previstes. En el seu lloc, s'utilitzen referències a recursos que solen ser específics de cada API. Consulteu la documentació de cada API per saber si la invocació sense operació està disponible i per conèixer la seva sintaxi específica.

Com que internament les APIs utilitzen sempre la invocació amb operació, els missatges d'error inclouen les peticions en aquesta forma, amb independència de com van ser especificades per l'usuari.

2.1. Codis de resposta i errors

En cas que el servidor no pugui atendre la petició, el codi retornat serà 500 (Server Error) o 503 (Service Unavailable). En la resta de casos, podem distingir dos tipus de petició que retornen diferents codis de resposta HTTP:

• Correcta: retorna el codi de resposta 200 (OK).
• Incorrecta: retorna el codi de resposta 400 (Bad Request). Com que alguns clients intercepten el contingut de la resposta quan el codi és d'error, per conveniència es pot forçar el codi 200 (OK) afegint a la petició el paràmetre rc amb valor 200 (aquest paràmetre s'ignorarà si s'especifica un altre valor).

En el cas de petició incorrecta, el document retornat contindrà el codi d'error (id), un text explicatiu en l'idioma sol·licitat per la petició (text) i la petició (query) tal com l'ha interpretada el servidor d'APIs. Si la petició no especificava un dels formats previstos per alguna API, s'utilitzarà XML en la resposta.

Ex. 8: Contingut de la resposta XML a la petició en un format erroni

<?xml version="1.0" encoding="utf-8" ?>
<errors>
   <error>
      <id>105</id>
      <text xml:lang="ca">
          "sas" no és un format vàlid (xml, json, php) de l'operació cerca de la versió v1 del servei pob.
      </text>
   </error>
   <query>http://api.idescat.cat/pob/v1/cerca.sas?q=abrera</query>
</errors>

Ex. 9: Contingut de la resposta JSON a la petició d'una operació inexistent

{
   "error":[
      {
         "id":"104",
         "text":"\"search\" no és una operació vàlida (cerca, sug) de la versió v1 del servei pob."
      }
   ],
   "query":"http:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera"
}

Ex. 10: Contingut de la resposta en format PHP serialitzat a una petició sense versió

a:2:{
   s:5:"error";
   a:1:{
      i:0;
      a:2:{
         s:2:"id";
         s:3:"002";
         s:4:"text";
         s:79:"Per al servei indicadors cal especificar una versió (v1).";
      }
   }
   s:5:"query";
   s:55:"http:\/\/api.idescat.cat\/indicadors\/dades.php";
}

Ex. 11: Contingut de la resposta en format text a una petició que no suporta aquest format per al servei/versió/operació especificats

***ERROR***
105
"txt" no és un format vàlid (xml, json, php) de l'operació cerca de la versió v1 del servei pob.
http://api.idescat.cat/pob/v1/cerca.txt?q=abrera

Els codis d'error indiquen si no s'ha especificat en la petició una informació requerida o si s'ha fet amb un valor incorrecte (i la informació no preveu un valor per defecte):

Codis d'error

	Falta	Valor incorrecte
Servei	001	101
Versió	002	102
Subservei	003	103
Operació	004	104
Format	005	105
Paràmetre	006	106

2.2. Formats suportats

En l'actualitat, els formats de resposta suportats amb caràcter general són XML, JSON i PHP serialitzat. Per a més informació, consulteu la secció 1.1.3 Format.