API Changes - how to know when they are made

Hi there.

We have recently fallen afoul of a change to the API for charges, additional fields were added that we hadn’t set to be ignored. This in itself is fine, I’m aware that the api is in flux and in beta, however I would appreciate a feed, RSS, or email, something so that we know the shape of the api responses has or will change. This would be useful to protect against failures but also to potentially take advantage of changes.

Perhaps this already exists, but I haven’t found it, but if not, I’d like to request it :smile:

Many thanks,
Mitch.

1 Like

You’re preaching to the choir. We’ve ended up essentially monitoring responses for unknown fields / values, and periodically doing a kind of diff-ing on the documentation to see if something’s changed. (This is a pain since due to “features” in CH API and the documentation we also need to keep note of “known issues” and our patches…) Updates to enum constants do tend to get announced on the forum however.

Plans to version the API (for each resource!) via mime types / content negotiation were mooted in 2015, see:

Then there was the idea of an update system for the enumeration constants. The developer documentation states (“enumuration” is theirs):

A planned enhancement to the enumuration scheme is the provision of API endpoints that will return the enumuration class catalogue. This avoids having enumurations hard-coded within a client, and by periodically checking for change through ETags, avoids clients having to download the full catalogue unnecessarily.

Looks like this stalled around 2015:

Various folks have thoughts about how it should be / could be:

There have been plans to “stream” various parts of CH now available as data dumps, if at all. These include PSCs, I can’t see whether officers were to appear also but that would be logical.
Streaming of PSCs seem to have stalled in 2017, see:

1 Like

Thanks @voracityemail - response much appreciated. I’ve seen the pinned post but also that it was written in 2015 so was hoping to find something a little more up to date. I searched but came up short. The above is a good grouping of relevant requests though and, at the very least, should help any other recent searchers.

Perhaps, as there has been api changes recently, this topic can be reviewed again internally at CH.

Hi Mitch,

Apologies for the problems you have had finding the API changes. The changes are posted in this forum with the labels “API changes” and “Information”. Here’s the link: http://forum.aws.chdev.org/c/api-changes/information

Which recent changes have caused you problems?

Thank you,

Joanne

Hi Joanne.

Thanks for your response. I have seen that forum but there is no recent activity there.

Specific example include new field “delivered_on” and “created_on” in ChargeDetails.

Many thanks,
Mitch.

@mitch_kent maybe post some examples with your queries and the responses - is the data type not the normal date format? These are not new fields - checking our own code they were there since before Feb 2017. They’re in some documentation I archived and in current documentation for the chargeDetails resource and the chargeList resource (which should also contain these fields). The type is given as “date”.

We’ve found that apart from the occasional undocumented field appearing the main issue of this kind is that sometimes the type of data returned doesn’t match the documentation e.g. nulls, numbers or even arrays where strings were expected. The format may also be incorrect. Date fields seem to be a frequent culprit - we’ve encountered values of “null”, “Unknown” and Unix timestamps for these. Examples reported (old):

We validate CH returns because “still beta”…

Hi again @voracityemail and thanks again for your detailed response.

The issue we had was easily resolved, and I no longer have a “problem” in the technical sense so I need no assistance, I was just looking for a way to be kept up to date about API changes.