Migrating to API version 2.4

Updating your integration to Citizen Space Public API version 2.4

Citizen Space Public API version 2.4 is the latest version of the API.

If your integration currently uses API version 2.0, 2.1, 2.2 or 2.3, you should update it to use version 2.4.

The requests you make to the API have not changed, so in most cases upgrading simply means changing the API version used by your integration. This is in the path, so for example, the API to our demo site is https://demo.citizenspace.com/api/2.4

There are however, some differences in the data returned by version 2.4. Depending on the version you currently use, you may need to update the way your application processes API responses.

This article explains what has changed and what you should check before moving to version 2.4.

Who needs to make changes?

You need to review your integration if it currently uses:

  • API version 2.0
  • API version 2.1
  • API version 2.2
  • API version 2.3

How to upgrade

Update your integration so that requests which currently use version 2.0, 2.1, 2.2 or 2.3 instead use version 2.4: api/2.4/

The request format and available request parameters have not changed in 2.1 to 2.4. There is one request argument change when upgrading from 2.0 to 2.4 (see below).

You should then check any code that reads or processes the API response. The changes you need to account for depend on which API version you are upgrading from.

We recommend testing your integration against version 2.4 before making the change in your production system.

If you are upgrading from version 2.3

There is one response change to be aware of.

Activity type names

The type_string     field now contains the activity type's current display name.

In version 2.3, some activity types were returned using the fixed names:

  • Explanatory Text    
  • Downloadable Document    

In version 2.4, type_string     instead contains the name of the activity type as it appears on your Citizen Space site.

If your integration checks type_string     for a particular fixed value, you should review this logic and make sure it can handle the activity type names returned by your site.

If you are upgrading from version 2.2

You need to account for all of the version 2.3 changes described above, as well as the following changes.

Areas, audiences and interests now contain objects

The following fields have changed:

  • areas    
  • audiences    
  • interests    

In version 2.2, these fields contain lists of IDs.

In version 2.4, each field contains a list of objects. Each object has:

  • an id    
  • a name    

For example, code which previously expected a list containing only identifiers will need to be updated to read the id     from each object instead.

You can also use the new name     value if your integration needs the human-readable name of an area, audience or interest.

Fields may not be present when a feature is disabled

The areas    , audiences     and interests     fields are only included when the corresponding feature is enabled on your Citizen Space site.

Your integration should therefore not assume that these fields will always be present in the response.

For example, version 2.2 always returned an areas     field. If areas were disabled, it was returned as an empty list.

In version 2.4, the areas     field is left out of the response entirely when areas are disabled.

The same approach applies to audiences     and interests  .

When processing a version 2.4 response, your integration should handle these fields as optional.

If you are upgrading from version 2.1

You need to account for all of the version 2.2 and version 2.3 changes described above, as well as the following change:

Activities without start or end dates are included in search results

Version 2.4 can return activities that do not have a start date or an end date.

When one of these dates has not been set, its value in the API response is null    .

Version 2.1 excluded these activities from search results.

This means an API version 2.4 search may return more activities than the equivalent version 2.1 search.

If your integration processes activity dates, make sure it can handle a null     start date or end date rather than assuming both dates will always contain a value.

If you are upgrading from version 2.0

All changes listed for versions 2.1, 2.2 and 2.3, plus:

The `extended` request argument has been replaced by `fields`. Use `fields=extended` for the extended fields, or `fields=all` for every field. If you still send `extended`, it's ignored and you'll only receive the basic fields.

What should I test?

Before switching your production integration to version 2.4, we recommend checking that your application:

  • does not rely on type_string     containing the fixed values Explanatory Text     or Downloadable Document    
  • expects areas    , audiences     and interests     to contain objects with id     and name     attributes
  • can handle areas    , audiences     and interests     being absent from a response
  • can handle null     start or end dates
  • does not rely on activities without dates being excluded from search results
  • is not sending 'extended' in the request

Once these cases are handled, requests made using the previous API versions should otherwise continue to work when changed to version 2.4.