Having an open API is great for allowing partners to build on your SaaS product. However, when I've been involved in integrations that use other people's APIs I've often thought that the construction of the API has only been considered from one perspective. "People will want to use the functions, utilities and data we have created, so let's allow them to access it!" But what about the user story where my external system is informed of events that have occurred within yours? Polling for changes seems very old fashioned, and incredibly wasteful and inefficient. What we need is an event based system that can inform external parties of appropriate events they want to hear about. We're talking about webhooks, callbacks etc
The problem tends to end up being "solved" with bespoke calls to specific partners. We need a more generic solution. An architecture utilising a workflow engine will allow events to be raised that can call 3rd party end points, but where WE have defined the data that will be sent. I stick by the “Keep It Simple, Stupid”, and advocate the simplest of data structures... one that lets the 3rd party know what entity type is involved, what has happened (Created, Updated, Deleted), and the IDs (both internal and external). The only additional piece of info you could add would be the URL to the API call that would retrieve the specific entity. It is then up to the 3rd party to decide whether they wish to Read the entity to capture the data.
