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]

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/{…}

L'identificador del servei determina l'element arrel del document retornat.

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:

• 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

2.1 Codis de resposta

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 tres tipus de petició que retornen diferents codis de resposta HTTP:

• Correcta: retorna el codi de resposta 200 (OK).
• Sense especificació, o amb especificació incorrecta, de servei, versió, operació o format: retorna el codi de resposta 404 (Not Found), llevat que faltin totes aquestes especificacions. En aquest cas, redirecciona (301) a aquesta documentació.
• Sense especificació d'algun paràmetre obligatori del servei/operació especificat: retorna el codi de resposta 400 (Bad Request).

En el darrer cas, el document retornat contindrà informació del servei que l'ha generat, el codi d'error (dins l'element error) i el paràmetre o paràmetres obligatoris dels quals no s'ha especificat valor (dins d'un element missing per a cada paràmetre absent).

Ex. 8: Petició errònia

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

Ex. 9: Contingut de la resposta a la petició errònia

<?xml version="1.0" encoding="utf-8" ?>
<indicadors version="1.00" o="dades">
   <error>400</error>
   <missing>i</missing>
</indicadors>

2.2 Formats suportats

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