Good APIs should accept foreign keys

I’m automating online marketing for event organizers at MotorsportReg.com by synchronizing event listings with third party calendars. I’m working with a typical API which is modeled such that you create a venue, they return an ID and then you use that ID in your event creation call. Pretty standard stuff.

The challenge is when I want to update or synchronize the listings later. The search makes it difficult to identify an event or venue that I’ve created in the system vs. one that someone else has created (which may have different attributes) or determine if I’m selecting the matching item at all (do we trust a string comparison on the name?) The venues in this API do support an arbitrary properties collection where I could stash an ID from our system but you can’t search based on those properties which results in searching, then looping to see if a property matches our original request and, if not, creating a new venue.

It doesn’t have to be that tedious. As a rule of thumb, any API which allows the creation of a logical object (people, events, places, etc) where the record of authority may originate from another system should accommodate a foreign identifier as a standard property and allow searching against the identifier.

I’m sure there are APIs which follow this practice but it should be a standard. Simplify my integration efforts so that I can easily send and synchronize data with you. Keep us loosely coupled. It’s one more field on your end or it’s a ton of code on my end that results in a more fragile relationship. Don’t make me maintain my own database table of ID mappings.

Update May 2015 – Since writing this, I’ve found another dozen instances where this would be valuable and plan to bake this into the second version of our API. However, I’ve come to believe that webhooks are an alternative 80% solution. Rather than polling and synchronizing, receiving a webhook when events of interest take place saves me the typical flow of grabbing a set of records, looping over them and comparing them locally for changes. The best of both worlds would be for the webhook payload to include my foreign key.