API

Decidim comes with a powerful API in read-only mode based on in the GraphQL specification.

Documentation for this API is auto-generated in each instance of Decidim, usually under the URL:

https://example.org/api/docs

Accessing that URL will give a full details of all the objects that can be requested and how. It includes the full field types reference. Note that the API can be slightly different for different Decidim instances and versions.

Using the GraphQL API

The GraphQL format is a JSON formatted text that is specified in a query. Response is a JSON object as well. For details about specification check the official GraphQL site.

Exercise caution when utilizing the output of this API, as it may include HTML that has not been escaped. Take particular care in handling this data, specially if you intend to render it on a webpage.

For instance, you can check the version of a Decidim installation by using different technologies and languages:

curl -sSH "Content-Type: application/json" \
  -d '{"query": "{ decidim { version } }"}' \
  https://www.decidim.barcelona/api/

const url = "https://www.decidim.barcelona/api/";
const query = "{ decidim { version } }";

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query }),
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

import requests

url = "https://www.decidim.barcelona/api/"
query = "{ decidim { version } }"

headers = {
    "Content-Type": "application/json"
}

response = requests.post(
    url,
    json={"query": query},
    headers=headers
)

print(response.json())

require "net/http"
require "uri"
require "json"

uri = URI.parse("https://www.decidim.barcelona/api/")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request.body = {
  query: "{ decidim { version } }"
}.to_json

response = http.request(request)
puts JSON.parse(response.body)

Note that Content-Type needs to be specified.

The query can also be used in GraphiQL, in that case you can skip the "query" text:

{
  decidim {
    version
  }
}

Response (formatted) should look something like this:

{
  "data": {
    "decidim": {
      "version": "0.18.1"
    }
  }
}

The most practical way to experiment with GraphQL, however, is just to use the in-browser IDE GraphiQL. It provides access to the documentation and auto-complete (use CTRL-Space) for writing queries.

From now on, we will skip the "query" keyword for the purpose of readability. You can skip it too if you are using GraphiQL, if you are querying directly (by using CURL for instance) you will need to include it.

Usage limits

Decidim is just a Rails application, meaning that any particular installation may implement custom limits in order to access the API (and the application in general).

By default (particular installations may change that), API uses the same limitations as the whole Decidim website, provided by the Gem Rack::Attack. These are 100 maximum requests per minute per IP to prevent DoS attacks