I’m working on a new project that will create a web-based API to perform CRUD operations on a relational database.
Originally, I was going to create the API as http-based, and make it RESTful so that – for example – operations on a person record might look like:
PUT /api/person/create/Sally/Smith/[email protected]
or
GET /api/person/findByEmail/[email protected]
For Create and Read.
However, I’ve since swapped out the http layer (node/express) for an http/ websockets layer (node/express.io). I’ve created realtime routes so that now, once a client has an open socket connection, they could perform the same actions as above with:
socket.emit('person:create', {firstname: 'Sally', lastname: 'Smith', email: '[email protected]'});
and
socket.emit('person:select', {email: '[email protected]'});
In one sense, this kinda sorta meets the constraints of REST (it is client/server, it is “stateless” in that no request relies on a prior request, etc.) but it feels like calling this pattern “RESTful” is wrong.
Is it? If it’s not REST, what is it?
14
There are a few things that make this API not very RESTful:
REST API URLs identify resources, not actions. First, actions should not be part of the URL path. The actions are the different HTTP methods. Instead of doing something like GET /api/person/findByEmail/[email protected], you should remove findByEmail and use query parameters to convey that you’re searching by email, e.g. GET /api/[email protected]. Notice that I also changed from person to people, since collections should generally be noted as plurals of the resources they contain. This resource reads as ‘People who have the email address [email protected]’, and with the GET method your request becomes ‘Get me the people who have the email address [email protected]’.
Second, PUT should always be idempotent, and the way you’re using it is not. In other words, if the PUT method accidentally gets called more times than it was meant to, it won’t really matter.
When to use PUT: When you are placing a resource at a specific location, e.g. if you want to put a song resource at /api/playlists/5/tracks/1. If this gets called more than once, it won’t really have a different outcome. Note, placing something might even mean placing something that wasn’t previously in the system. PUT can create a resource on the back-end or in the persistence layer somewhere if it doesn’t already exist before placing it at the specified location. The key point here is you’re not saying ‘create a user and give me a URL to reference said user’, you’re saying ‘create a user that looks like this and put said user at this URL’. This request could read as ‘Put the following song as the first track in playlist 5’
When to use POST: When you are creating a resource, and it’s up to the server to create a URL for the resource. An example would be creating a user, much like you’re trying to do, which could be done as so: POST /api/people?firstName=Sally&lastName=Smith&[email protected]. Another way to do this would simply be to use POST /api/people and pass in as the body of the request a person object containing those details, e.g.:
{
firstName: "Sally",
lastName: "Smith",
email: "[email protected]"
}
The response would have a Location : api/people/1 header indicating that the person resource lives at that URL. If you called it a second time, it might give you Location : api/people/2. Each subsequent POST should give you a new URL for the newly created resource because you’re creating a new one each time it’s called. Note that by nature, POST requests are generally not idempotent.
So whatever it is, I wouldn’t call it REST. As far as what you can call it, I would say that’s up to you. I guess you should ask yourself if it actually matters what you call it, and if there’s anything wrong with just calling it a ‘websockets API’.