Construct the Resource Hierarchy
By: Rain Wu
Tags: API, Software Engineering, Web Development, Technology, Software Development

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.

Photo by Unsplash

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.

Photo by Unsplash

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.

Photo by Unsplash

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

Photo by Unsplash

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.