Best practice : REST API Resource Naming
Rejoy!! Let’s have a coffee. Ok boss!!! So what is the REST API and what should be the best practice for naming it ?
What is REST?
In 2000, Roy Fielding proposed Representational State Transfer (REST) as an architectural approach to designing web services.
REST is an architectural style for building distributed systems based on hypermedia.REST is independent of any underlying protocol and is not necessarily tied to HTTP.
Advantages
The primary advantage of REST over HTTP is that it uses open standards. It does not bind the implementation of the API or the client applications to any specific implementation.
Ex : A REST service could be written in Spring (Java) and the client application can use any language which can generate HTTP request and parse HTTP response.
In REST, the primary data representation is called resource.
Singleton and Collection Resources
A resource can be a singleton or a collection.
For example, “cars” is a collection resource and “car” is a singleton resource.We can identify “cars” collection resource using the URI “/cars“. We can identify a single “car” resource using the URI “/cars/{carId}“.
REST API endpoints naming best practices
“Beauty is power; a smile is its sword”… so if you maintains the beauty, the code will be more readable as well as more maintainable.
Followings are few tips can be follow for REST API naming strategies.
URIs resources as Nouns
RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) .
RESTful URIs should not indicate any kind of CRUD (Create, Read, Update, Delete) functionality.
Example: /cars/{id} instead of /getCar
Never use CRUD function names in URIs
The URI should not indicate a CRUD function. URIs should only be used to uniquely identify the resources and not any action upon them.
We should use HTTP request methods to indicate which CRUD function is performed.
#Don’thttp://api.example.com/getUsers
http://api.example.com/createUser
http://api.example.com/saveUser
http://api.example.com/deleteUser
http://api.example.com/getUserByUserId#Do’sHTTP GET http://api.example.com/users //Get all users
HTTP POST http://api.example.com/users // Create user
HTTP GET http://api.example.com/users/{userId} //Get specific user
HTTP DELETE http://api.example.com/users/{userId} //DELETE specific user
Forward slashes for hierarchy
The forward-slash (/) character can be used in the path portion of the URI to indicate a hierarchical relationship between resources.
http://api.example.com/users/{id}/addressDo not use trailing forward slash (/) in URIs
The last character within a URI’s path, a forward slash (/) has no semantic value. It’s better to drop it from the URI.
http://api.example.com/users/
#Do's
http://api.example.com/usersUse hyphens (-) to improve the readability of URIs
To make your long URIs easy to scan and interpret, use the hyphen (-) character to improve the readability of names.
http://api.example.com/device-management/managed-devicesDo not use underscores ( _ )
It’s possible to use an underscore in place of a hyphen to be used as a separator — But depending on the application’s font, it is possible that the underscore (_) character can either get partially obscured or completely hidden in some browsers or screens.
To avoid this confusion, use hyphens (-) instead of underscores ( _ ).
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readablehttp://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable
Return Proper HTTP Status code
Conclusion
In this article, we have covered the best prctices for REST API namings. For java naming convention, you can follow the official site.
References :
