It's not always 200 OK

When creating the Cronofy API, we didn’t just want to create a one API for all the calendar services, we wanted to deal with many of the problems when integrating with those APIs individually.

Through judicious use of the less commonly encountered 202 Accepted we’ve endeavoured to do just that.

A definition

202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

For our purposes, the request will always eventually be acted upon. However, it is true that it might be disallowed when processing actually takes place. For example, the credentials for the user may no longer be valid. In that case we will get the user to authenticate again and then reattempt the request, all without you having to be involved. Also, the calendar service may be down temporarily, which I’ll go into later, amongst various other potential problems.

When acting as an intermediary between you and the calendar services, this response is the most accurate description of what is actually happening, and it has some other benefits too.

Shaving yaks

A common source of pain when integrating with a new API is creating a mapping table from your internal data to the ID determined by the API. There’s also the complexity of knowing whether you need to issue an insert for a new event or an update for an existing one.

We wanted to deal with all this complexity for you and so decided on an “upsert” model for creating and updating events. You give us a value uniquely identifying the event you want to create within your system and we worry about the actions required to make that into reality. No mapping required, no response to parse containing all the information you just sent us, just a 202 Accepted and the knowledge we’ll update your users calendar as soon as possible.

Embracing failure

Another thing we felt we had to deal with for you was downstream failure. All calendar providers can, and do, have downtime and if we were to directly proxy your requests you would have to deal with the consequences of that yourself.

We are all about making things as smooth for you as possible so that isn’t acceptable. Therefore, as much as is possible, each downstream action we need to perform on your behalf is done asynchronously via a queue and background processors.

This queuing infrastructure allows us to shield you from downstream failure, continuing to attempt to make the change you requested in the face of failure without you having to worry or create similar infrastructure yourself.

Even if the worst happens and a problem occurs whilst you are talking to our API you don’t need to worry. There’s not the problem of your “create” succeeding but you not having the ID so you cannot update it later, your delete succeeding and so a subsequent one will result in an error, you can just try again. You can just tell us the state you want an event to be in and we’ll make sure the event in your customer’s calendar reflects that.

All this is why our response for create or update, and delete, event requests is 202 Accepted. Everything might not be 200 OK right now, but once it is we’ll make sure that the world looks the way you want it to.

What do you think? Is this 200 OK or 406 Not Acceptable? Let us know on Twitter.

‍