Interfaz de programación de aplicaciones (API)

1.1 Anatomía de las peticiones

Toda petición debe especificar obligatoriamente un servicio, la versión principal del servicio, una operación válida por este servicio y un formato de respuesta. Opcionalmente, se pueden especificar una serie de parámetros generales y específicos del servicio.

http://api.idescat.cat/{servicio}/v{versión principal}/{operación}.{formato}[?parámetros]

1.1.1 Servicio y versión

Cada servicio dispone de un identificador, de una versión y de unos parámetros específicos. Por ejemplo, el servicio de Indicadores al día se identifica con el valor indicadors y sólo dispone de una versión (1).

Ej. 1: Petición a la versión 1 del servicio de Indicadores al día

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

El identificador del servicio determina el elemento raíz del documento retornado.

Los servicios pueden tener diferentes versiones principales, incompatibles entre sí. Las mejoras incrementales no afectan a la versión principal (por ejemplo, 1.01 respecto a 1.00) y, por lo tanto, tampoco a la petición.

1.1.2 Operación

Los servicios suelen soportar una diversidad de operaciones. Por ejemplo, el servicio indicadors admite la operación dades, que retorna resultados estadísticos, pero también la operación nodes.

Ej. 2: Dos peticiones al mismo servicio pero a operaciones diferentes

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

El servicio y la operación determinan la estructura del documento retornado.

1.1.3 Formato

Determina el formato de la salida. Admite tres valores:

• xml: retorna el resultado en formato eXtensible Markup Language.
• json: retorna el resultado en formato JavaScript Object Notation. Esta salida reproduce fielmente toda la información que retorna la petición en formato XML. Permite especificar una función de devolución con el parámetro callback con el nombre de la función. Aunque JSON es una cadena codificada en UTF-8, por conveniencia, la salida en este formato tienen en cuenta el valor especificado en enc.
• php: retorna el resultado en formato PHP serializado. Esta salida tiene la misma estructura que la salida en formato JSON: se trata de una cadena que puede ser deserializada para crear un objeto PHP (no una matriz). En este caso, el resultado siempre se retorna codificado en UTF-8 con independencia del valor de enc.

Ej. 3: Varias peticiones con respuesta en diferentes formatos

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ámetros generales

Toda petición tiene unos parámetros generales (comunes a todos los servicios) y unos parámetros específicos del servicio, documentados en la API del servicio.

1.2.1 Idioma de la respuesta (lang)

Admite tres valores:

• ca: catalán (valor por defecto)
• es: castellano
• en: inglés

Ej. 4: Resultado en castellano

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

1.2.2 Codificación de la respuesta (enc)

Este parámetro admite dos valores: utf-8 (valor por defecto) e iso-8859-1.

Ej. 5: Resultado codificado en ISO-8859-1

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

Si el formato de la respuesta es php la codificación es UTF-8, sea cual sea el valor de enc.

1.3 Parámetros específicos

Además de los parámetros generales descritos en el apartado anterior, cada servicio admite unos parámetros específicos ("variables") que permiten configurar la información obtenida. Estos parámetros están documentados en la API del servicio.

Por ejemplo, la operación dades del servicio indicadors permite seleccionar el número de indicadores obtenidos gracias a los parámetros tt, max y min.

Ej. 6: Parámetros específicos

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

1.3.1 El parámetro general p

Las variables del servicio (o "parámetros específicos") pueden encapsularse en un parámetro general para efectuar una llamada más compacta. Para hacerlo hay que incluir una serie de parejas variable/valor separadas por puntos y coma.

Ej. 7: Peticiones sinónimas

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 Códigos de respuesta

En caso de que el servidor no pueda atender la petición, el código retornado será 500 (Server Error) o 503 (Service Unavailable). En el resto de casos, podemos distinguir tres tipos de petición que retornan diferentes códigos de respuesta HTTP:

• Correcta: retorna el código de respuesta 200 (OK).
• Sin especificación, o con especificación incorrecta, de servicio, versión, operación o formato: retorna el código de respuesta 404 (Not Found), salvo que falten todas estas especificaciones. En este caso, redirecciona (301) a esta documentación.
• Sin especificación de algún parámetro obligatorio del servicio/operación especificado: retorna el código de respuesta 400 (Bad Request).

En el último caso, el documento retornado contendrá información del servicio que lo ha generado, el código de error (dentro del elemento error) y el parámetro o parámetros obligatorios de los cuales no se ha especificado valor (dentro de un elemento missing para cada parámetro ausente).

Ej. 8: Petición errónea

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

Ej. 9: Contenido de la respuesta a la petición errónea

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

2.2 Formatos soportados

En la actualidad, los formatos de salida soportados son XML, JSON y PHP serializado. Para más información, consulte la sección 1.1.3 Formato.