coolfarmer coolfarmer - 27 days ago 15
reST (reStructuredText) Question

Restful resource naming for "secondary" tables

Let's go with my example, I have 3 tables and I want to know what's the best method to name my resource url.

Tables:


  1. building

  2. building_type The most simple to define is #1.



API resources:


  1. GET someapi.com/buildings

  2. GET someapi.com/**?**



My problem is that I don't know what's the best practice for "secondary tables" like building_type.

Maybe:


  • GET someapi.com/buildings/types

  • GET someapi.com/building-types

  • ...



I hope some of you will reach to enlighten me. Thanks.

Answer

You first need to figure our the requirements for your API, the scenarios, use cases etc, and only then actually start building it.

To go back to your question, I'd go for GET someapi.com/buildingTypes, because /buildings/types will leave you with a "Types" resource which doesn't make much sense on it's own. You could indeed make it so it's only accessible once you go to the buildings resource, so GET someapi.com/buildings/buildingTypes could be the way to navigate to it.