OK after my readings this afternoon, I’m ready to land on the question of Resources in REST.
In a practical sense, REST is all about representation. So when you’re building your API RESTfully, the representations you build really depend on the usage of the system.
The idea of a Resource is that there’s some unifying idea behind those representations. That is, I can represent an instance of a customer resource as JSON or as XML or as PDF. Whatever.
However, the idea of Resource is just a placeholder. We’re like Plato in his cave, insisting that the shadows on the wall (the representations) come from some sort of true forms outside the cave (the resources).
But anyone implementing REST has exactly the same problems Plato had with his metaphor. For example, if you take the true form of a chair and stretch it, when does it become a bench? If you start plucking hairs from the true form of a man, at what point does he become a bald man?
Similarly, does a customer resource include the customer’s address? A list of addresses? A list of their payment methods? Are those different representations of the customer, or different resources?
There’s a real trap in defining REST services getting hung up on the definition of Resources.
Some are easy. We might have a database table, which is naturally well-defined, and maybe we can even draw a border around a set of related tables that have foreign key relationships to our table. Wrap it up and we can call it a Resource.
But many are not easy. Search results is the classic case. What is the underlying Resource for a search? Well, the underlying resource is some view on the universe of data we’re searching on. It’s not just one thing.
Sometimes the underlying resource is completely transient. The Resource could be the result of a calculation that we perform. We can’t point to data that lives in our system anywhere and call our resource that.
REST is all about the interface. Save your modelling for the lower-level bits of the system, and just think very, very broadly about what you’re willing to identify as Resources.
As engineers, we spend so much time in our world providing clarity around our data model, whether it’s a database schema, and object model, or even a file of comma-separated values, that it pains us when we hit a generic term like Resource, that can’t always be defined with that precision.
I used to start on an application and ask, what Resources do I have? That answer might be helpful, but really the critical question is, what Resources do I need?
(The final word is “need”.)