0

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/ssmith@acmeco.com

or

GET /api/person/findByEmail/ssmith@acmeco.com

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: 'ssmith@acmeco.com'});

and

socket.emit('person:select', {email: 'ssmith@acmeco.com'});

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? – Robert Harvey Feb 23 '15 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? – GojiraDeMonstah Feb 23 '15 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 '15 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. – GojiraDeMonstah Feb 23 '15 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." – Robert Harvey Feb 23 '15 at 17:14
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/ssmith@acmeco.com, you should remove findByEmail and use query parameters to convey that you're searching by email, e.g. GET /api/people?email=ssmith@acmeco.com. 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 ssmith@acmeco.com', and with the GET method your request becomes 'Get me the people who have the email address ssmith@acmeco.com'.

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=ssmith@acmeco.com. 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: "ssmith@acmeco.com"
}

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, privacy policy and cookie policy

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