Top REST API URL naming convention standards
There is no sanctioning body or open source linter that can verify if a RESTful API conforms and complies with all applicable REST API naming conventions and best practices.
However, REST API developers should follow certain industry-wide accepted naming conventions and guidelines.
Guidelines for naming RESTful APIs
Some of these best practices for naming RESTful APIs are tied tightly to the rules about how best to format URLs for HTTP. Others stem from the technical guidance in Roy Fielding's dissertation on representational state transfer.
Regardless of their inspiration, one should follow all the REST naming conventions to create an API that is easy to follow and work with and complies with the standards expected of a RESTful resource.
REST API URL naming conventions
The following list represents the standard set of REST API naming conventions and best practices that software architects should follow when they develop and design RESTful APIs:
- Only use lowercase letters in RESTful API URLs.
- For white space, use kebab-case, not snake_case or spaces.
- Build URIs with nouns, not verbs.
- Use the appropriate HTTP methods to perform an operation.
- REST API calls that return a collection should be plural.
- A URL that returns a unique result should be singular.
- Don't include file extensions.
- Use headers to keep URIs clean.
- Don't identify create, read, update and delete -- CRUD -- operations in the URL.
- Structure URIs loosely on your data model's hierarchy.
- Use query parameters for filtering and search.
- Don't expose the internal workings of your architecture.
- Make URLs short, intuitive and readable.
- Protect yourself against SQL injection.
- Include the REST API version at the base of the URI.
Best practices for naming RESTful URLs
Software architects and developers have a great deal of flexibility to develop RESTful APIs. While nobody wants to limit the creativity of the dev team, they should follow these REST API naming conventions, guidelines and best practices to produce an API that is maximally readable, interoperable and immediately understandable.
Raghu Karan Adapala is a full-stack developer, app architect and cloud enthusiast with expertise in React, Node.js, TypeScript, Python, Docker, Terraform, Jenkins and Git.