A good friend of mine was out walking his dog in the countryside the other day. After a while, his dog noticed some turkeys in the adjacent field, and being a dog, decided to investigate. This involved some barking and general running up and down along the fence. I suppose, in the dog’s mind, he was telling the turkeys that he was defending his master and they should not come any closer. The turkeys responded with a cacophony of gobbling and rapid gurgling. The dog got scared and now has a phobia for turkeys…

This often happens when we want to share a message with a wider audience. We have something we want to say. We’ve identified the audience. We start to speak and the response is completely different from what we expected. The dog, barking at the turkeys, expects them to run away. The turkeys do the opposite, running back towards the dog and shouting “Hey! New Guy” (in turkey talk). Leaving the dog scared and confused.

To give you an example from my daily work with APIs; I was involved in a meeting recently where I ended up in a divergent debate with another architect on what the profile of a customer meant. Turns out, the opposing opinions were brought about by lack of context; I was assuming a retail customer (person) while he was assuming a corporate customer (organization). A context in any communication is crucial.

Does this mean we should start every conversation by giving some context? Yes, probably a good idea, but I believe it may be more relevant to start by assuming your audience does not have the same context as you. If you begin with that context (pun intended), you will probably begin by providing context to your audience before diving into the details.

This is also the approach we should take with APIs. During a verbal conversation, we have the opportunity to change tack or adjust our speech to provide an explanation or context. With APIs, we don’t have this luxury. REST APIs are based on resources. Resource sometimes need context to have more meaning. Encapsulating this resource within some context could offer meaning, but might create a confusing data contract. Ideally, we should provide context via the URL.

Let’s look at an example. Assuming I need to consume an API that presents transactions on my account. The URL 

https://api.somedomain.com/transactions 

could return this list of transactions, but they have no context – they could be for anyone’s accounts. We could provide context to these transactions by including the account these transactions belong to. For example 

https://somedomain.com/accounts/12345/transactions 

makes the statement that these transactions belong to the account identified by “12345”. It’s a simple and seemingly innocuous approach, it can be very powerful, but often forgotten or missed.

Craig Hughes