Ideas Bank

Most software updates come with release notes, and many online services do the same. For something like JustGiving, where charities using need processes in place to manage high volume of data - it's essential that any changes - particularly upcoming ones - should be communicated effectively.

These should both be:

1) published on a website that anyone can visit and see a list of recent changes AND upcoming changes (roadmap). This allows charities AND developers to understand what has / will change and make necessary decisions.

2) sent out via email to all charity account holders (with communication preferences so employees not involved can opt out). This is a standard practice amongst almost all online service providers, e.g. Stripe, MailChimp, GoCardless etc.

Upcoming changes / Roadmap should be in the categories of:

a) in discussions - where charities can give input about potential issues

b) upcoming - where charities have had chances to feedback and it's already in development for deploying, with clearly specified dates of when the change will happen

Examples of why not doing this can be business breaking:

We had a developer built a web system that uses the JustGiving API to pull in newly registered fundraising pages. The data are then interpreted into a useful format for our team to manage (assign Fundraiser IDs, nominal codes etc). The system also provided a link to the page itself so our team could see the current page's details.

However, at some point in 2018, the page url output changed from just the last part of the URL to becoming the full URL - which broke our web system, as it then prefixed with the http part of the url twice.

Besides the fact that APIs should not ever be changed in production, and that new versions of the API should be pushed out instead - there were no way for us to know that the change was coming, and the developer was not immediately available after the changes to help us fix it.

Another example is when recently, guest checkouts may include 'some' information, instead of being anonymous - this also introduced unexpected behaviours in our system due to the system was built when originally when Donor User Id was unique for every donor.

We understood that something changed (again in 2018) when all guest checkouts had the same Donor User Id - but since they were all anonymous - our system wasn't affected.

But now, with unique details to guests who share details, and Donor User Id still recycled for all of them - it's broken our system's output.

These issues - if communicated to charities BEFORE being applied - would have allowed us to

a) give feedback and suggestions (e.g. guests who checkout whilst sharing details should have unique Donor User Ids)

b) give us an opportunity to make changes in advance to when the changes happen, rather than scrambling in panic AFTER it happens.

Final note:

API changes should ALWAYS be done to new versions (even if minor version change), with the version number of the API being part of the request URL to separate multiple versions. This is standard practice for how APIs should be developed and managed - it's something that is intended for software to software interfaces with no human input. ANY changes can be system breaking.

Entire version of an API can be deprecated before being discontinued with advanced warning so that older systems can continue to operate for a reasonable amount of time as new / updates are made to work with new versions.

For examples, see Twitter (currently 1.1 with 2.0 on early access) https://developer.twitter.com/en/docs/twitter-api; discord (currently v8 with v6 deprecated) https://discord.com/developers/docs/reference