Digicollect API v1 documentation

Introduction

Welcome to the Digicollect API documentation.

The Digicollect API allows you to read data from your Digicollect site and integrate it in your own software.

Authentication

All API requests must use a secure HTTP connection (HTTPS) to "api.digicollect.nl". For authentication you need to provide an API key as parameter (api_key) or header (this is the preferred way, the header name is X-Api-Key). If no API key or an invalid key is provided, the status code 401 will be returned. Please contact support@kentaa.nl to get an API key for your Digicollect site.

For example, when you have an API key "12345", then the following will be a valid API request:

GET https://api.digicollect.nl/v1/donations?api_key=12345

Example for a valid API request using curl and authentication via header:

curl -H "X-Api-Key: 12345" https://api.digicollect.nl/v1/donations

Requests

The following HTTP request types are supported:

• GET - Request to one or more resources. The result will be returned as JSON.
• POST - Create a new resource and return the result as JSON.
• PATCH - Update attribute(s) of a resource and return the result as JSON.

Responses

The API will return the following HTTP status codes for a request:

• 200 OK - The GET or PATCH request was successful.
• 201 Created - The POST request was successful.
• 400 Bad Request - The request contains an invalid parameter or payload.
• 401 Unauthorized - No valid API key was provided (see above how to authenticate).
• 403 Forbidden - Access to the requested resource was denied.
• 404 Not Found - A requested resource could not be found.
• 422 Unprocessable - Entity could not be processed because fields were missing or invalid.
• 500 Server Error - Something went wrong on the server side when trying to process the request.

For a successful GET request, the response body will include one or more JSON objects with the requested data. The key will always be the resource that was requested, the singular form when one object was requested or the plural form when requesting a multiple objects.

A successful POST response body will include one JSON object with the newly created data.

A successful PATCH response body will include one JSON object with the newly updated resource.

For example, the response for requesting a single object or creating an object:

{
  "donation": {
    "id": 1,
    ...
  }
}

Example response for requesting multiple objects:

{
  "donations": [
    {
      "id": 1,
      ...
    },
    {
      "id": 2,
      ...
    }
  ]
}

Pagination

Requests that return many objects (List operations) will be limited to 25 objects by default. When more results are available, the response will include a links object with first/last/prev/next links.

Sample links object:

{
  "links": {
    "pages": {
      "last": "https://api.digicollect.nl/v1/donations?page=34",
      "next": "https://api.digicollect.nl/v1/donations?page=2"
    }
  }
}

You can use the following parameters to specify pages and to customize the page size:

• page (default: 1) - page number
• per_page (default: 25, max: 100) - number of objects to return per page

Curl example for retrieving a maximum of 100 donations with page number 1:

curl -H "X-Api-Key: 12345" "https://api.digicollect.nl/v1/donations?per_page=100&page=1"

The response will also include the following keys to supply information about the number of available objects and the current pagination:

{
  "total_entries": 30,
  "total_pages": 3,
  "per_page": 10,
  "current_page": 1
}

New and updated objects

Each object includes the attributes created_at and updated_at which indicate when the record was created (created_at) and when the record was last changed (updated_at). These attributes can be used as filter to retrieve only new or updated objects.

For all requests that return many objects (List operations) you can the following parameters to return new or updated objects after a given datetime:

• created_after - return only objects that were created after the given datetime (ordered by created_at)
• updated_after - return only objects that were updated after the given datetime (ordered by updated_at)

Both parameters are a datetime in ISO 8601 format.

Curl example for retrieving donations created on and after midnight (UTC) on 1 January 2016:

curl -H "X-Api-Key: 12345" "https://api.digicollect.nl/v1/donations?created_after=2015-12-31T23:59:59Z"