Identifying Resources from Requirements

Resources do not come from databases, frameworks, or other existing ways of modeling data. They come from requirements. More specifically, they come from understanding what users want to do and what concepts they talk about when describing their needs and identifying the different roles.

The best way, in my experience, to identify resources is to start with user stories or business requirements and analyze them carefully before writing a single line of code.

From user stories to resources

User stories are usually written in natural language and describe intent rather than implementation. This makes them an excellent starting point for resource discovery.

Consider the following example from a library system:

As a user, I want to see a list of authors so that I can browse available books.
As a user, I want to borrow a book from the library.
As a librarian, I want to manage books so that the catalog stays up to date.

Even without any technical background, several concepts immediately stand out. Authors and books are clearly central to the domain. Borrowing and managing are actions performed on top of those concepts.

A useful exercise at this stage is to extract three elements from each requirement:

• Actors
• Nouns
• Actions

The nouns often indicate candidate resources. The actions tell us what can be done with them and the actor is the one performing those actions.

Separating resources from actions

A common mistake is to turn actions directly into endpoints. For example, it might be tempting to create endpoints like /borrowBook or /addAuthor. While these may work functionally, they obscure the underlying model and lead to inconsistent APIs.

In REST, actions are expressed through HTTP methods, not through resource names. Borrowing a book is not a resource called borrow. It is an operation performed on a book or on a related resource.

A more expressive design might involve a resource such as:

POST /books/{id}/borrowings

Here, borrowing is modeled as a sub-resource that represents the act of borrowing, rather than a verb embedded in the URL.

Actors do not define resources

Another subtle trap is confusing actors with resources. Users, administrators, and staff members perform actions, but they do not necessarily imply different resources.

The same resource can be accessed by different actors with different permissions. For example, a bookkeeper might be allowed to update book information, while a regular user might only be allowed to view it. This is an authorization concern, not a resource modeling concern.

Resource identification should focus on what exists, not on who interacts with it. Then, we could have different representations of the same resource depending on who is performing actions on it.

When requirements are unclear

Resource identification becomes difficult when requirements are vague or constantly changing. Agile environments often amplify this challenge. While change is expected, uncontrolled change during implementation leads to unstable APIs.

A good rule of thumb is to stabilize requirements at least for the duration of a sprint or release. Resource design should be revisited deliberately and proactively, not reactively.

Spending time clarifying requirements early reduces costly redesigns later. It is much easier to rename or restructure a resource on paper than after it in a live API being consumed by multiple clients.

Resource identification is iterative

Identifying resources is not a one time activity. As systems grow, new concepts appear and existing ones evolve. The goal is not to get everything right upfront, but to build a solid initial model that can adapt over time as the system scales.

The better the resource model reflects the domain language, the longer it will remain relevant.

If you like what you've read so far or resonate with my opinions, consider subscribing. It's free!.