Please, don’t call them RESTful
Last year I tweeted something similar about the REST architectural paradigm.
In fact, most people believe that to build a RESTful API you can simply create an API based on URLs and HTTP verbs. This is absolutely false.
If you ask around ten developers if their APIs support HATEOAS, at least nine will look at you with wide eyes saying: what f***ing are you talking about?
Yet the name speaks for itself. REST’s name says nothing about the protocols to be used and the way to identify a resource. It just speaks about REpresentational State Transfer. And state transfer management is a mandatory requirement for an API to be called RESTful, as Roy Fielding has stressed.
A true RESTful API is an API that provides the client with a new state and ways to switch to subsequent states. It provides a representation of a resource (not necessarily in JSON) and enriched links (hypermedia) to other related resources that may move the application to another state, as in the following example:
Here, the resource describes itself and provides information about related resources.
To be picky, it does not matter whether you use HTTP or another protocol. The key thing of the REST approach is that the server addresses the client state transitions. The state of the client is almost totally driven by the server and for this reason discussions on the API versioning make little sense, too. All that a client should know about a RESTful interface should only be the entry point. The rest should come from the interpretation of server responses. This is an interesting scenario rarely implemented.
APIs that simply map CRUD actions to HTTP verbs have nothing to do with Application State Transfer. You can call them Web APIs or HTTP APIs, but please don’t call them RESTful.