Where are the Resources?

This is a question I find myself asking the technologists and product teams behind REST APIs over and over again. All too often, the “architecture” implements the data access mechanics directly in the API, and there is no distinct model for the Resources being surfaced by the API.

You may be thinking the API itself surfaces the resource model and that’s all fine. But it’s not- it causes real harm to the effectiveness of a system. The following, abbreviated list are a few real-world examples of problems that I have seen manifest in such designs:

• Non-idempotent, unsafe GETs
• Duplicated work/code  – loss of maintainability
• Granularity of services gets fixed- loss of flexibility
• Loss of ability to implement application/object cache effectively

When approaching the specification and design for a REST API, start with the use cases (or user stories, scenarios, whatever terminology you prefer), and then do some information architecture and modeling- this will drive your Resource Model. Note that your Resource Model is driven by business requirements for information – not the data models of the participating applications and data stores.

This drives the need to separate the Resource Model from both the API processing, which may need to assemble multiple Resources into a more coarse-grained Resource dynamically, and the mechanics of data access, which may be heterogeneous or subject to change over time.

So, if you find yourself working on a project that includes implementing ReST services, ask yourself, and your team, “Where are the Resources?”


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s