👋🏽Hey Techies! I hope your hashnode journey sounds good. If yes, Today I'm going to explain best naming conventions for API endpoints.
As we know that all REST APIs have a URL at which they can be accessed, e.g. api.example.com. Subdirectories of this URL denote different API resources, which are accessed using a Uniform Resource Identifier (URI). Naming resources make sense and can be understood by anyone. For example, the URI api.example.com/users will return a list containing the users of a particular service.

1. Use forward slashes

✅ api.example.com/articles/authors

Forward slashes(“/”) are conventionally used to show the hierarchy between individual URI resources and collections.

2. Use Nouns, not verbs

❌ api.example.com/getUsers
✅ api.example.com/users

When naming the URIs, you should use nouns to describe what the resource is and not what it does. This is because CRUD (create, read, update, delete) functionality should already be specified in the HTTP request (Ex. HTTP GET api.example.com/users). There is no need to repeat the information, which keeps the URI easy to read while showing that it is the Get Method needed.

3. Use plural nouns

❌ api.example.com/api/profile/21
✅ api.example.com/api/profiles/21

This makes it clear that there is more than one resource within a collection. Using singular nouns can be confusing.

4. Lowercase letters :

As a standard, URLs are typed in lowercase. The same applies to API URIs. Lowercase letters for URIs are in widespread use, and also help avoid confusion about inconsistent capitalization. If you add capital letters, you should be aware that this will cause confusion and result in user error more often than not.

5. Use hyphens to separate words

✅ api.example.com/users/123/first-name

When a REST API endpoint contains multiple words, you should separate the words with hyphens. It’s a good way to make the URI easier to read and is a universal method that everyone can understand. Hyphens are the most user-friendly way and are a better choice than underscores.

6. Never use file extensions

❌ api.example.com/api/profiles.xml
✅ api.example.com/api/profiles

There is no purpose in using file extensions in URIs. They are unnecessary and only make it harder to read clearly.

7. Use versioning

✅ example.com/api/v2/articles

Make sure you create a new version of your API if you're making major changes that could break it. This is usually indicated in endpoints by adding the version at the start of the endpoint.

8. Query parameters where necessary

✅ api.example.com/users?location=USA

In order to sort or filter a collection, a REST API should allow query parameters to be passed in the URI. Above URI finds all users living in the United States.

Be Consistent with Naming REST API Endpoints

Choose a system for naming your API endpoints and stick to it. You should document your methods so everyone working with you knows the naming protocols. When you are consistent in your names, this ensures a uniform system across the board. Everyone working with the APIs will find it easy to use them. If they’re unsure of a specific URI, they can assume what it will be, based on the naming protocols. Maintain records of everything. While there are some generally understood guidelines across the board, you may want to formalize the process. When someone new joins your team, they can quickly access the URI naming protocols and follow them to ensure consistency.