How Resource Restrictive REST URIs Save API Design
A common problem with REST is unintentional categorization. Many creators of REST resources include words in the URL that are unnecessary and provide no value, which lead to problems. Using unnecessary words (unknowingly) limits the URL’s semantical construction, which leaves less room for resource extension.
Consider a resource restrictive REST URI as a definitive resource. What does the term “resource restrictive” URI mean? Each word in a resource restrictive URI structure should lead to a data source. For instance, a tree structure that usually has something underneath⎯e.g. /Music/Artists/Albums/Songs, where music contains all music, artists contains musical artists, and the artists albums are another resource one layer deeper.
Music |-Artists |-Albums |-Songs
Every layer reveals an additional concrete resource/s. If I navigate to music, I should see a list of artists. If I navigate to an artist, I should see a list of music belonging to the artist.
Many REST URIs are non-restrictive. In addition, non-restrictive REST URIs provide no value in the URI, only to categorize, not inform.
For example, a REST URI such as /Collection/Music/Received/Songs has no hierarchical value other than categorizing the music as songs received. Navigating the structure reveals nothing for Collection, Music or Received. Results are only returned when you arrive at songs. Do you recognize the design flaw?
If the structure type described was the path, where would you add Albums or Artists?
A well, thought-out resource restrictive URI saves future headaches when trying to add additional resources to a hierarchy. The reason many REST resources only have one resource at the end of a long URI string is because the URI is not well developed. There is nowhere to go after the endpoint.