Do’s and Don’ts : Naming REST API

Vishwas Trivedi
4 min readDec 16, 2022

Web developers are no strangers to APIs — especially HTTP methods like GET and POST. When it comes to designing APIs, backend engineers or API engineers are familiar with them as well. That means REST is a term that is familiar. It is said that REST is an architecture and not a standard. It was developed alongside HTTP and is most commonly used over HTTP. HTTP is a standard, whereas REST is an architecture. REST is an architectural style that provides constraints that guide API design.

While REST APIs are extremely useful, creating them can be a time-consuming process. If you are building your own REST or RESTful API, you should know that there are best practices to follow. This includes the naming of your REST API endpoints.

Following are the global standards that should be followed while naming REST API Endpoints.

  1. Use nouns
  2. User intuitive, clear names
  3. User lowercase letters
  4. Avoid special characters
  5. Separate words from hyphens
  6. Don’t use file extensions
  7. Use camelCase for designing

1. Use Nouns

When naming your URIs, it is advised to use nouns instead of verbs or adjectives. HTTP methods are technically verbs, hence GET, POST, DELETE, etc. Also, the names represent the contents of a resource or the resources themselves. Hence, it makes more sense to actually use nouns instead.

Do

https://api.example.com/users/abcd-efgh-ijkl

Well, you get what I mean. Basically, when you look at the URL, you can tell that it is accessing the User resource with a particular ID as per the above example.

Don’t

https://api.example.com/getUsers/abcd-efgh-ijkl
https://api.example.com/create_users
https://api.example.com/delete-users/abcd-efgh-ijkl

It simply looks funny. Also, the browser would tell you that the URL is using the GET/POST/DELETE method if you inspect, so there is no need to add the action word to your URI.

Now the interesting question is whether to use singular or plural nouns. In general, plural nouns are preferred, as they represent more of something generic in a sense (unless your resource is a singular concept like “admin” or “config”).

2. User intuitive, clear names

--

--

Vishwas Trivedi

I am an accomplished Software Engineer/ Project Manager with 8.5 years of technical experience in driving successful software development teams.