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?”