Application Programming Interface (API)

1.1. Anatomy of requests

All requests must specify a service, the main version of the service, a valid operation for the service and a response format. Optionally, a series of general and specific parameters for the service can be specified.

http://api.idescat.cat/{service}/v{main version}/{operation}.{format}[?parameters]

Some services can share the syntax of requests and the structure of responses. These are treated as a single service that offers subservices. In this case, the form of the request is:

http://api.idescat.cat/{service}/v{main version}/{subservice}/{operation}.{format}[?parameters]

Although this is the form by which all requests are treated internally, the APIs also usually admit a more user-friendly external syntax that does not require an operation to be specified (see Invocation without operation).

1.1.1. Service and version

Each service has an identifier, a version and some specific parameters. For example, the Indicators of the day service is identified using the value indicators and has only one version (1).

Ex. 1: Request in version 1 of the Indicators of the day service

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

The services may have different main versions that are incompatible with each other. Incremental improvements do not affect the main version (for example, 1.01 with respect to 1.00) and therefore do no affect the request either.

1.1.2. Operation

The services tend to support a diversity of operations. For example, the service indicators admits the operation data, which returns statistical results, but also the operation nodes.

Ex. 2: Two requests for the same service but different operations

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

The identifier and the operation determine the structure of the returned document.

1.1.3. Format

It determines the response format. It admits three values in general:

• xml: returns the result in eXtensible Markup Language format.
• json: returns the result in JavaScript Object Notation format. This output faithfully reproduces all the information returned for the request in XML format. It enables specification of a callback function using the parameter callback with the name of the function. Although JSON is a UTF-8 encoded string, for reasons of convenience, the output in this format takes into account the specified value for enc.
• php: returns the result in serialised PHP format. This output has the same structure as that of output in JSON format: it is a string that can be deserialised to create a PHP object (not an array). In this case, the result is always returned UTF-8 encoded regardless of the value for enc.

Ex. 3: Different requests with different response 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. General parameters

Every request has some general parameters (common to all services) and some specific parameters of the service, documented in the API of the service.

1.2.1. Response language (lang)

It admits three values:

• ca: Catalan (default value)
• es: Spanish
• en: English

Ex. 4: Result in Spanish

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

1.2.2. Response encoding (enc)

This parameter admits two values: utf-8 (default value) and iso-8859-1.

Ex. 5: ISO-8859-1 encoded result

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

If the response output is php the encoding is UTF-8, whatever the value for enc.

1.3. Specific parameters

As well as the general parameters described in the previous section, each service admits certain specific parameters ("variables") that can configure the information obtained. These parameters are documented in the service's API.

For example, the operation data of the service indicators can be used to select the number of indicators obtained thanks to the parameters tt, max and min.

Ex. 6: Specific parameters

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

1.3.1. General parameter p

The service variables (or "specific parameters") can be encapsulated in a general parameter to make a more compact call. To do so, a series of variable/value pairs must be included separated by semicolons.

Ex. 7: Synonymous requests

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. Invocation without operation

For reasons of user-friendliness, some APIs can admit requests with a syntax that does not require one of the generally provided operations to be specified. Instead, they use references to resources that tend to be specific to each API. See the documentation on each API to find out whether the invocation without operation is available and its specific syntax.

As APIs always use the invocation with operation internally, the error messages include the requests in this form, regardless of how they were specified by the user.

2.1. Response codes and errors

Should the server not be able to attend to the request, the code returned will be 500 (Server Error) or 503 (Service Unavailable). In other cases, we can distinguish two types of request that return different HTTP response codes:

• Correct: returns response code 200 (OK).
• Incorrect: returns response code 400 (Bad Request). As some clients intercept the content of the response when the code is an error, for convenience code 200 (OK) can be forced, adding to the request the rc parameter with value 200 (this parameter will be ignored if another value is specified).

In the case of incorrect request, the returned document will contain the error code (id), an explanatory text in the language required by the request (text) and the request (query) as interpreted by the APIs server. If the request did not specify one of the formats provided for an API, it will use XML in the response.

Ex. 8: Content of an XML response to a request in an erroneous format

<?xml version="1.0" encoding="utf-8" ?>
<errors>
   <error>
      <id>105</id>
      <text xml:lang="en">
          "sas" is not a valid format (xml, json, php) for the cerca operation in version v1 of the service pob.
      </text>
   </error>
   <query>http://api.idescat.cat/pob/v1/cerca.sas?q=abrera&amp;lang=en</query>
</errors>

Ex. 9: Content of a JSON response to a request in an inexistent format

{
   "error":[
      {
         "id":"104",
         "text":"\"search\" is not a valid operation (cerca, sug) for version v1 of the service pob."
      }
   ],
   "query":"http:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera&lang=en"
}

Ex. 10: Content of a response in serialised PHP format to a request without version

a:2:{
   s:5:"error";
   a:1:{
      i:0;
      a:2:{
         s:2:"id";
         s:3:"002";
         s:4:"text";
         s:79:"For the indicadors service, you must specify a version (v1).";
      }
   }
   s:5:"query";
   s:55:"http:\/\/api.idescat.cat\/indicadors\/dades.php?lang=es";
}

Ex. 11: Content of a response in text format to a request that does not support this format for the specified service/version/operation

***ERROR***
105
"txt" is not a valid format (xml, json, php) for the cerca operation in version v1 of the service pob.
http://api.idescat.cat/pob/v1/cerca.txt?q=abrera&lang=en

The error codes indicate that a required information has not been specified or that this has been done using an incorrect value (and the information does has a default value):

Error codes

	Missing	Incorrect value
Service	001	101
Version	002	102
Subservice	003	103
Operation	004	104
Format	005	105
Parameter	006	106

2.2. Supported formats

At present, the response formats supported in general are XML, JSON and serialised PHP. For further information, see section 1.1.3. Format.