API Endpoint Naming Best Practices

1. Use forward slash

  • Use forward slashes for resource hierarchy and to separate URI resources.
  • Example: https://test.api.com/articles/authors

2. Use nouns, not verbs

  • When naming the URIs, you should use nouns to describe what the resource is and not what it does. For example:

 Wrong:   https://test.api.com/api/getProfiles
 Correct: https://test.api.com/api/profiles

3. Use plural nouns

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

 Wrong:  https://test.api.com/api/profile/21
 Correct: https://test.api.com/api/profiles/21

4. Lowercase letters

  • As a standard, URLs are typed in lowercase. The same applies to API URIs.

5. Use hyphens to separate words

  • When chaining words together, hyphens are the most user-friendly way and are a better choice than underscores.
  • For example: https://test.api.com/api/profiles/101/first-name

6. Never use file extensions

  • There is no purpose in using file extensions in URIs. They are unnecessary and only make it harder to read clearly.
  • Wrong: https://test.api.com/api/profiles.xml

7. Include versioning

  • 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.
  • For example: https://test.api.com/api/v2/articles
Next Recommended Reading Web API Self-Hosting