Changing hierarchy of already existing RESTful resources

Yair Zaslavsky
4 min readApr 21, 2019
Inverloch, Victoria, Australia

Mission statement:

RESTful web services are extremely popular today as a mean to serve requests from web and mobile applications.
The “folder like” path structure of URLs is widely used to describe a hierarchy of resources, where usually the resource name appears in a plural form , followed by a resource unique identifier for a single resource, then a sub resource (in a plural form),a unique id for the sub resource and so on..

At times , the hierarchical structure of the resources needs to change. Adding a resource which is a child of the the last resource in the hierarchical structure is easy. But what happens if a resource should be added at the top of the hierarchy?

A concrete example to the above described problem:

Let’s say you are a Java developer, working with Spring boot (or Spring MVC) , and you develop a set of REST controllers for a zoo web application.

The suggested domain model includes the following resources:

1. The zoo itself as the root of the hierarchy.

2. Sections : these are areas in the zoo that contain several animal displays. Each section has a unique name and a set of coordinates that define its borders.

3. Animal display: an animal display is basically a set of animals from the same type (i.e: a display of lions)

4. Animals: a resource that describes each animal in a display

Your team discusses several approaches for API versioning , and decides to adopt a URL based versioning.
The team agrees the resource URLs will have a prefix of “/api/v1/zoo”.

The zoo resource has a single instance, as the web application serves a single zoo.

Some implementation details:

You decide to implement a base controller class, that among other things contains a constant that defines the base path: