Versión 1

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.

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

Algunos servicios pueden compartir la sintaxis de las peticiones y la estructura de las respuestas. Estos son tratados como un único servicio que dispone de subservicios. En este caso, la forma de la petición es:

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

A pesar de que esta es la forma en la que internamente son tratadas todas las peticiones, las API también suelen admitir una sintaxis externa más amigable que no requiere especificar una operación (ver Invocación sin operación).

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

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

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

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

https://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 con carácter general:

• xml: retorna el resultado en formato eXtensible Markup Language.
• json: retorna el resultado en formato JavaScript Object Notation. 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

https://api.idescat.cat/indicadors/v1/dades.xml

https://api.idescat.cat/indicadors/v1/dades.php

https://api.idescat.cat/indicadors/v1/dades.json

https://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

https://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

https://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

https://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

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

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

1.4. Invocación sin operación

Por razones de amigabilidad, algunas API pueden admitir peticiones con una sintaxis que no requiere especificar una de las operaciones generales previstas. En su lugar, se utilizan referencias a recursos que suelen ser específicos de cada API. Consulte la documentación de cada API para saber si la invocación sin operación está disponible y para conocer su sintaxis específica.

Como internamente las API utilizan siempre la invocación con operación, los mensajes de error incluyen las peticiones en esta forma, con independencia de cómo fueron especificadas por el usuario.

2.1. Códigos de respuesta y errores

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 dos tipos de petición que retornan diferentes códigos de respuesta HTTP:

• Correcta: retorna el código de respuesta 200 (OK).
• Incorrecta: retorna el código de respuesta 400 (Bad Request). Como algunos clientes interceptan el contenido de la respuesta cuando el código es de error, por conveniencia se puede forzar el código 200 (OK) añadiendo a la petición el parámetro rc con valor 200 (este parámetro se ignorará si se especifica otro valor).

En el caso de petición incorrecta, el documento retornado contendrá el código de error (id), un texto explicativo en el idioma solicitado por la petición (text) y la petición (query) tal como lo ha interpretado el servidor de API. Si la petición no especificaba uno de los formatos previstos por alguna API, se utilizará XML en la respuesta.

Ej. 8: Contenido de la respuesta XML a la petición en un formato erróneo

<?xml version="1.0" encoding="utf-8" ?>
<errors>
<error>
	<id>105</id>
	<text xml:lang="es">
		"sas" no es un formato válido (xml, json, php) de la operación cerca de la versión v1 del servicio pob.
	</text>
</error>
<query>https://api.idescat.cat/pob/v1/cerca.sas?q=abrera&amp;lang=es</query>
</errors>

Ej. 9: Contenido de la respuesta JSON a la petición de una operación inexistente

{
"error":[
	{
		"id":"104",
		"text":"\"search\" no es una operación válida (cerca, sug) de la versión v1 del servicio pob."
	}
],
"query":"https:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera&lang=es"
}

Ej. 10: Contenido de la respuesta en formato PHP serializado a una petición sin versión

a:2:{
s:5:"error";
a:1:{
	i:0;
	a:2:{
		s:2:"id";
		s:3:"002";
		s:4:"text";
		s:79:"Para el servicio indicadors hay que especificar una versión (v1).";
	}
}
s:5:"query";
s:56:"https:\/\/api.idescat.cat\/indicadors\/dades.php?lang=es";
}

Ej. 11: Contenido de la respuesta en formato texto a una petición que no soporta este formato para el servicio/versión/operación especificados

***ERROR***
105
"txt" no es un formato válido (xml, json, php) de la operación cerca de la versión v1 del servicio pob.
https://api.idescat.cat/pob/v1/cerca.txt?q=abrera&lang=es

Los códigos de error indican si no se ha especificado en la petición una información requerida o si se ha efectuado con un valor incorrecto (y la información no prevé un valor por defecto):

Códigos de error

	Falta	Valor incorrecto
Servicio	001	101
Versión	002	102
Subservicio	003	103
Operación	004	104
Formato	005	105
Parámetro	006	106

2.2. Formatos soportados

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