beginner

API routes naming conventions

Now its time to talk about REST API routes naming convention. People usually get lost on how to name their routes especially when multiple models are in play for the same endpoint.

Rules

1 - Always use plural form(if applicable)

  • ✅ /users
  • ❌ /user
  • (plural form is not applicable and therefore using it is actually wrong)
  • ✅ /history
  • ❌ /histories

2 - Always use kebab-case (hypens and lowercase)

  • ✅ /users
  • ❌ /Users
  • ✅ /phone-numbers
  • ❌ /Phone-numbers
  • ❌ /phone_numbers
  • ❌ /phoneNumbers

3 - Use resources not verbs

  • ✅ /users
  • ❌ /createUsers

4 - Use parameters to indicate which resource you want

  • ✅ /users/:id (example: /users/5 will return user with id 5)

5 - Rely on HTTP method to indicate intent

  • ✅ GET /users - get all users
  • ✅ GET /users/:id - get user with that specific id
  • ✅ POST /users - creates new user
  • ✅ PATCH /users/:id - update user with that specific id
  • ✅ DELETE /users/:id - delete user with that specific id

6 - Use nesting endpoints for relationships (only 2 level deep)

  • ✅ /users/:userId/posts - get all posts for user with specific id
  • ❌ /users/:userId/posts/:postId/comments
  • (instead use:)
  • ✅ /posts/:postId/comments?userId=5

7 - Use query string (either as snake_case or camelCase)

  • ✅ /posts/:postId/comments?user_id=5
  • ✅ /posts/:postId/comments?userId=5
  • ✅ /posts/:postId/comments?limit=10&sortBy=...&search=...

8 - Version your API

  • ✅ /api/v1/posts
  • ❌ /posts/

API versioning

Once your application is in production you can’t just change what response you are sending back, you have to maintain backwards compatibility. Imagine if you initially return this reponse:

{
  success:true,
  message:{
    id:...
    name:...
  }
}

and then you change it to this:

{
  success:true,
  data:{
    id:...
    name:...
  }
}

it is insanely small change but you just broke whoever is consuming this API because they are expecting message property but are receiving data instead. Now you might say “oh but I can just send them a message or notify them”. Well, yes but not really because:

  • - They expect it to just work once implementation is done
  • - They rely on stability of API they are using (which in this case is your API)
  • - They are who knows where in their development
  • - If its a more complex change in response that means a lot of development on their side depending on their usecase
  • - What if newer version has bugs?

And you can say “okay, makes sense, but no one is using this API just me on my own frontend”. And while this makes it a lot easier to implement changes you still need to version because:


  • - If you first change your response then your frontend will throw error and it no longer works
  • - If you first change your frontend then you need to include multiple if else statements to keep track of what response you get and then once you implement it in backend you need to again remove those statements and make it only use newer version
  • - What if newer version has bugs? What if frontend changes have bugs on implementing changes?

With all of this in mind, the proper approach is to maintain backwards compatibility and to notifiy whoever is using your API of a EOL(end of life) for a specific API version. This EOL is anywhere between 1 year to few years depending on many things.

Make sure you never remove or change anything existing from previous version(s). Adding new things is okay(but should be avoided if possible) but you should not make it a requirement to use the newly added property in the previous version. The reason is simple: by removing/changing you are breaking backwards compatibility but by adding you are not breaking it.

Folder structure

index.js
routes.js
Route.js
Ignitor.js
Transformers(folder)
 - SucessTransformer.js
Models(folder)
 - User.js
Controllers(folder)
 - UserController.js
package.json
package-lock.json
.env
node_modules(folder)
Previous Introducing views and transformers
Next