Contacts API behaviour changed

1

Hi,

We use the API to keep our customer data up to date and trigger sending invoices.

The API used to Upsert contacts depending on whether you passed a contact URL with the contact. So we’d have a new contact created if there wasn’t one already and existing ones would update nicely. It worked well for years.

We’ve noticed this has changed so now all of our calls to the API have created new contacts. Our code wasn’t set up to handle this scenario and we now have many duplicated contacts, hundreds of out of date ones and invoices are being sent with out of date details.

Undocumented and surprise FreeAgent API changes have caused us issues on numerous occasions. Can someone point me to a resource that has up to date, reliable information on when changes have happened so we can at least keep up to date, or are there plans to introduce API versioning so we can migrate properly?

Thanks

Gareth

2

Hi Gareth,

I have been trying to reproduce the upserts for the contacts endpoint however I am unable to.
As I understand it, the upserts happened on POSTing to /v2/contacts, depending on the presence of a url attribute in the request payload?

Could you let us know the name of your app (as registered in Dev Dashboard) and paste a sanitised version of your API requests here?

It is likely that you have stumbled upon undocumented (but useful) behaviour here. The API expects POST for creating and PUT for updating resources. Upserts do seem like a good future addition to the API, so any help in debugging this would be appreciated!

Regards,
Ioan

3

Hi Ioan,

Thanks for getting back to me,

I don’t think the upserts work any more, hence us having a broken implementation. In all honesty it’s probably good that they don’t - it’s clearer and more consistent that the API now sticks to the PUT and POST actions.

My understanding is we always sent a POST to the /v2/contacts endpoint and pre-populated the URL field with the URL of the existing contact ID if we knew it.

The app name is: “Timetastic freeagent integration”
ID: 3184

We may have stumbled across undocumented features and although the API does (now) expect a proper rest implementation, we need a process for notice that it’s changing. I appreciate you can’t plan every implementation to the last minute, but there needs to be some communication about what’s changing and roughly when.

I’m glad it’s improving and the implementation is more consistent and robust - but this is the 3rd or 4th time in about 12 months we’ve had to spend time scrambling around to deal with an API change from FreeAgent with absolutely no notice at all.

4

Hi Gareth,

Thanks for your reply.

The UPSERT functionality you’re describing for contacts isn’t something the documented API supports. While I appreciate it’s something you’ve clearly been relying on, I’m afraid you’ve been relying on an unreported bug that looks like it’s recently been fixed, most likely by some update to an internal subsystem.

That said, and as Ioan points out, it would be incredibly useful to have this behaviour documented and fully supported. What we’ve been trying to do is understand when it last worked, so we can see if it’s something that’s easily restored. So far, though, we’ve been unable to pinpoint a recent point in history when it was possible, so would appreciate your help in tracking that down.

We know how disruptive breaking changes to APIs can be, and genuinely try our best to ensure documented API functionality doesn’t change without notice to developers (and certainly not without unavoidable good cause!). However, it sounds like there have been other cases recently where you’ve seen documented functionality change without warning? I’d really appreciate it if you could give me some details so we can investigate those further, as these sorts of change-without-notice are most definitely not intentional.

Thanks,

-JB

5

Hi Jonathan,

I can’t say exactly when it stopped working but it was within the last 6 months. I’ll ask around the team to see if there’s any way we can find out - I’m writing code to specifically de-duplicate all the contacts, so I’ll see if I can pull creation dates off those and trace it back that way.

Other instances of changes with no notice we’ve had:

  • 13th November 2017 invoices and bank transaction explanations changed.
  • Rate limits came in and we found out once our code started returning 429s. The forums suggested anyone affected would be notified, but we weren’t.
  • I have a vague recollection that invoice statuses changed once and that caused issues - it may have been related to the above bank transaction explanation issue, but I can’t recall exactly.

There’s more, this is just from notes I’ve found in the app I use to fix things. An email list, twitter feed or something that just says “yo guys, check your logs over the next few days” would be awesome.

Thanks for taking this so seriously, appreciate it.

6

Hi Gareth,

Thanks for getting back to me with some specific examples, that’s really helpful. I’ll dig into them in a moment, but to your point about:

An email list, twitter feed or something that just says “yo guys, check your logs over the next few days” would be awesome.

Part of the problem with the “check your logs” approach is that where we suspect a knock-on effect to the API, we will work to ensure that effect doesn’t happen. If you see a change in API behaviour and it’s not been pre-announced here, it’s either a change to undocumented behaviour, or it’s a change we did not intend to make. In the latter case, we try to be as responsive as possible to reports of changes. In the former case (as with your initial query here), we will look to see if there’s a way we can make the undocumented behaviour robust enough to be restored and fully supported.

Regarding the “email list”, that would be this forum. You’re now a member, and hopefully you’ve set up email alerts so you have a fighting chance of seeing any future announcements we make. I realise we could do a better job of ensuring all developers are signed up to this forum, and we should consider ways of improving that in the future.

Finally, regarding your specific issues:

  • Please do let us know if you get an idea of when you saw the contacts API behaviour shift. Even if it’s a date when it definitely did work as you describe, it will help us pull code from that date and try to reproduce the behaviour to understand what has changed.

  • Rate limits: when introducing rate limits, we did reach out to any developers whose integrations were busy enough to have been immediately affected by their introduction. We also announced on here well before introducing them. I realise that’s not much use if you didn’t see the message, or if you started to breach the limits well after the announcement, so I apologise for that. Hopefully those posts help illustrate why we introduced rate limits, and that it wasn’t a decision we took lightly.

  • Invoices and bank transaction explanations: I’m guessing that’s this issue, which got flagged and fixed up as quickly as we could manage. Reading through that thread, it feels like there was maybe some confusion regarding which channel to raise a “support” query which caused a delay in resolution. This forum does perform multiple duties, but we should look at ways to improve response times here for suspected bugs and changed behaviour

Hopefully the above helps reassure you that we do take support of the API seriously, and I’d encourage you to continue to post questions and report unexpected behaviour here as you find it.

Thanks again for bearing with us, and for using our API.

Cheers,

-JB