Unfortunately, I still regularly run into articles on the web that misunderstand the concept of an HTTP resource. Considering it is a core piece of web architecture, having a clear understanding of what it means can make many other pieces of web architectural guidance considerably easier to understand.
To try and keep this post as practical as possible, let’s first consider some URLs.
How many resources are being identified by these five URLs?
If all of those requests return some kind of 2XX response, then there are five distinct information resources. The presence of query strings parameters, or path parameters, or verbs or nouns, or plurals or singular terms, has no bearing on the fact that that these are distinct web identifiers that identify distinct resources.
Time to set the record straight
Let me give a few examples that seem to confuse people:
- The URLs https://example.org/customers/10 and https://example.org/customers/11 are not the same resource.
- Query string parameters identify resources in exactly the same way that path parameters identify resources.
- Performing a HTTP GET returns a representation of only one resource, even if the URL is https://example.org/customers
- The URLs https://example.org/customers and https://example.org/customers?country=canada are two different resources even though the same controller returned the response.
Resources > Entities
Another common misconception is that resources are limited to exposing entities from your application domain. Here are some examples of resources that are perfectly valid despite what you might read on the internet:
It’s very simple
A resource is some piece of information that is exposed on the web using an URL as an identifier. Try not to read anything more into the definition than that.