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]


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]'});


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?

  • If it's not REST, will you give it up and find the thing that is REST? Feb 23, 2015 at 16:35
  • I'm not sure what you mean. Are you saying don't bother developing an API that doesn't strictly meet the REST requirements?
    – Gojira
    Feb 23, 2015 at 16:42
  • @GojiraDeMonstah I get the feeling he wants to say, just don't care. With websockets, I think it is hard to meet REST requirements at all. Also your PUT URI is not should not contain create.
    – Knerd
    Feb 23, 2015 at 16:45
  • I see. In that case, no, I don't want to chase a buzzword at the expense of developing something that works well for the requirements at hand. I posted this question because I had originally entered in the readme for my repo that it was a RESTful JSON api. If it is no longer that, I wanted to be more precise with my description.
    – Gojira
    Feb 23, 2015 at 16:48
  • 1
    My impression has always been that REST is particular to HTTP. Sure, it doesn't have to be HTTP, but the conventions that have evolved around the Fielding notion of REST all have to do with HTTP web services and the notion of "addressable resources." Feb 23, 2015 at 17:14

1 Answer 1


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'.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.