Construct the Resource Hierarchy

Published in

Random Life Journal

5 min readJul 21, 2020

Continue the previous article “From Requirements to Database Schema”, we already build an organized data storage system now. Now we want to access or operate them outside the system, we definitely will not allow the website visitor or service user to touch our database directly, that’s extremely crazy and dangerous.

A common way to provide an interface between the client-side and our storage system is a web server, it can handle requests and take some protective measures before operating the database. In some large-scale systems, reverse-proxy or some authentication mechanisms may also be integrated for security concerns.

But that’s far away from the subject of this story, we are not preparing to implement a defense system. In the following section, I will sketch the resource hierarchy and try to match the usage of the content platform, also make him the basis for implementing API in the next story.

Resource Hierarchy

Consider the length of ideal URI, we should avoid designing the resource hierarchy more than three-level deep. On the other hand, if an abstract concept like “sub-sub-resource” exists in your design, you may feel uncomfortable due to the long URI.

The resource user can exist independently without any concern, so we first put it at the root level:

- user

But how about the resource story and publication? Should they be a subresource of users? RESTful does not have clear instructions for this condition, but we can still evaluate the pros and cons of all aspects by ourselves.

Readability

One of the attractions of the hierarchical structure is that it contains more information than a flattened structure, which is also a tip that we should pay attention to when designing.

In the hierarchical structure, sub-resource belonged to its parent, and cannot exist outside the scope of its parent. If we follow this principle, we may be confused because of the ambiguous attribution:

- user
  - publication
  - story- tag

each publication belongs to a user (owner)
each story belongs to a user (author)
each story can be marked with multiple tags, but those tags do not belong to that story

Looks great! The maximum depth of the hierarchy structure is shallower than three, and no redundant item. But readability is not everything we have to consider, some practical issues may also encounter in the future.

Usability

How might the users use the webserver?

We should consider use cases as more as possible during the design process, just like converting requirements to a database schema.

If a webserver is a lack of usability, it may seriously affect the collaboration between backend and frontend or mobile apps. Some terrible problems like overly complex URI, or inefficient interaction.

Users may search for the content they are interested in, and the frontend or mobile app will help them send the requests. The hierarchical structure above can handle the user searching and the publications and stories of a specified user easily.

But will the user only do these operations?

As far as I am concerned, I will search the stories or publications by the keywords of prefix more often than access them under a specified user page directly. The following mechanism and recommended system also needs to search stories depend on the tag and publication?

Does our structure can easily handle these requests?

No, it can not.

We need too traverse all user resources and filter the story with a corresponding tag or publication, it almost an impossible case when the number of users exceeds a certain threshold. We had better put the publication and story resources to the root level for a better operating logic.

- user
  - publication
  - story- publication- story- tag

This hierarchy can execute the query to publications and stories directly without traversing subresources of all users.

Maintainability

A terrible resource hierarchy will result in RESTful APIs with high maintenance costs, which is also the most common complaint of back-end engineers. One of the problems we can simply avoid is redundant resources, like the publication and story above.

Because these may derivative extra API endpoints to maintain, both on your code within .py file and the text within the documents, and may leave potential risks if each endpoint’s behavior of the same resource is not consistent.

Strike a Balance and Wrap Up

After discussing many different aspects, a final resource hierarchy we would get. I prefer a flattened structure to fit the querying and searching requirements than a two-level model, of course, you can keep your design for this part with your reason.

- user- publication- story- tag

I think the searching mechanism is the backbone of the content platform and might be updated or improved very soon, so I want to keep it stay as flexible as possible. Meanwhile, the sub-resource could be removed, so does the redundant endpoints.

Conclusion

The above is the process of how I construct all of the resources into an organized hierarchy and how I make the decision between different structures. At least three aspects I will concern about and discuss with my college:

Readability
Usability
Maintainability

Resource architecture is an extreme case-oriented task, a better way to avoid much more cost of maintenance is to think more about how your server would be used, hope it helps you :)