7

Recently I have started using a new(to me) paradigm for web services. I use the controller to accept JSON strings sent over POST, process it and return JSON strings. GET, PUT, DELETE and other methods throw HTTP 405.

This pattern is proving to be very efficient from the point of view of asynchronous web frameworks (vert.x and play to be particular), as well as from development effort point of view.

What I am confused about is that this neither seems to be SOAP nor REST. I don't think it is even JSON-RPC, since I am using my own headers like:

Request:

{
  'requestId':<generated req Id>,
  'token':<previously authenticated token>,
  'action':<controller defined action>,
  'parameters':[
    <array of parameters>
  ]

}

Response:

{
  'result':'success/fail',
  'payload':{
     <payload>
   }
}

EDIT: There is only one endpoint URL, something like https://my.domain.com/api

Can anyone give any ideas about what this paradigm can be classified as?

Jit B
  • 373
  • 2
  • 9
  • 5
    "this neither seems to be SOAP nor REST". You seem to think SOAP and REST are the same kind of thing. REST is an architecture style, SOAP is a protocol (for example it defines a data exchange format, which REST doesn't). – Cyrille Ka Jul 24 '13 at 15:28
  • I know what SOAP and REST are. Please confirm - in SOAP we only use XML to define parts like envelope, body, header, etc and always use POST. In REST we use HTTP protocols like PUT/GET/POST/DELETE 'resources'. I would have used SOAP but I like JSON better than XML, and like to use my own headers. So it's kind of a SOAP-over-JSON-with-custom-headers. So is there any established web-service design pattern that matches this implementation. – Jit B Jul 24 '13 at 15:32
  • 2
    This appears to be REST using JSON, which is a very common use of REST. What makes you think that this is not REST? – David V Jul 24 '13 at 18:55
  • 3
    @DavidV This is not REST. Using POST and JSON for a URL does not qualify something to be REST. REST is about resources. It would be closer to JSON-RPC than it is to REST. – Andrew T Finnell Jul 24 '13 at 20:20
  • 1
    Is it technically REST? I dont know. Would I care that it wasnt if it was effectively solving the problem? Not one bit. People were passing all sorts of data and calling all sorts of remote functionality via http long before the term REST was coined. – GrandmasterB Jul 24 '13 at 21:03
  • @AndrewFinnell. From what we see in the post, it is hard to know if it is REST or not. From what I can see this can be REST. Maybe there are things we don't know that make it un-RESTful. My question is what is making the op think it is not REST. – David V Jul 24 '13 at 21:33
  • I dont think it's REST because we are not accessing remote resources using standard HTTP requests (why? - check my other comment in the answer given by @bye). So its close to JSON-RPC but not adhering to the set standards. But I am not sure whether I can use the term JSON-RPC when I tell other developers that the API uses this mechanism. – Jit B Jul 24 '13 at 23:18

3 Answers3

8

There are really two definitions of REST:

  1. Representational State Transfer ("REST") as a principle for service design (not necessarily web service!), which suggests a uniform client-server interface where the server does not store the client context, e.g. "client has visited this page last". As a general principle, RESTful services shuold request a specific resource -- e.g. an article, or an "order" object -- as well as an action to perform on that resource -- "get", "tag", "paint yellow", or whatever is necessary, so long as the same action for different types of resources gets the same name. So long as you follow these principles, your web service can be RESTful even if it does not use HTTP. I don't see the specific resource being requested in your protocol , but then again, it may be defined by the URL. EDIT: As you are not specifying the resource independently of the action, your service is not RESTful by this definition.

  2. REST as a specific request format that uses HTTP as carrier protocol and HTTP request types like GET, POST, or DELETE to specify what type of action needs to be carried out. Your service is obviously not RESTful by this definition.

The most general description of your protocol would be likely a service for remote procedure calls (RPC) over JSON, but which is not JSON-RPC.

To be clear, there is nothing wrong with not being RESTful or being RESTful. Whatever suits your needs.

ikh
  • 928
  • 7
  • 15
  • In particular, this does not seem to adhere to the "Uniform Interface" constraint: https://en.wikipedia.org/wiki/Representational_State_Transfer#Guiding_principles_of_a_REST_interface – Pete Jul 25 '13 at 02:08
  • It's hard to tell.. if in the above protocol URLs identify the resources and the actions are uniform, then it would likely be sufficient to meet the requirements of Uniform Interface principle. – ikh Jul 25 '13 at 02:20
  • The service endpoint is constant so each endpoint doesn't represent a unique resource. I edited the question. – Jit B Jul 25 '13 at 03:29
  • I don't think "paint yellow" might have place in REST. The set of operations in REST is intentionally limited to getting current state and setting new state (which creating and deleting objects is a special case of), but not actions. The point is that setting the same state again is a noop, greatly simplifying handling of network faults (if you don't get answer, you can blindly retry). – Jan Hudec Jul 25 '13 at 07:46
  • 1
    It's not RESTful. But it doesn't have to be. We can all use a lesson in pragmatism. If it suites the needs perfectly it doesn't have to fit into a RESTful pattern. But don't call something RESTful when it isn't. Now, based on what has been presented it COULD be restructured to be restful with a Task resource and the like. – Andrew T Finnell Jul 25 '13 at 14:37
3

REST has absolutely nothing to do with using standard HTTP methods. It is a design concept that might equally apply to any network protocol. What defines REST is the set of operations that only limit to getting state and setting new state, creation and deletion are special cases of which. Object is created by setting state of object with not yet used id (which must therefore be client-generated or prepared by separate query), deleting by setting object state to empty. Important property is that all the operations are idempotent, i.e. doing them twice in a row is exactly equivalent to doing them just once.

The question itself thus does not give enough information to decide whether the service is REST or not. But the comment at bye's answer mentions methods "COPY" and "MOVE" and these don't fit in REST (the only way to copy in rest is to get the state and upload it to new resource and the only way to move is to copy and than delete the original). That does not mean it's wrong. Nobody said REST is appropriate for all situations.

Jan Hudec
  • 18,250
  • 1
  • 39
  • 62
1

The problem is that you are creating Yet Another Interface. This is rather RPC-like.

I'm not saying RPC is bad. RPC seems to be easier for programmers to understand naturally. You can probably do everything in REST that you can do in RPC, but you have to get used to thinking in terms of moving resources rather than calling functions.

With a RESTful API, if I want to delete a record I send a DELETE request to /thing/3 and it gets deleted. If I want to get it I use a GET. It's a standard that I don't have to think about or look up.

One nice thing about REST is you can just use your browser to look at the API and get some data to see what it looks like. You can't with yours.

With yours, I have to know what to put in the action parameter. Maybe I put in the word DELETE, but I have to look that up.

With REST, I know that a 404 means that the record does not exist. With yours, I have to look at the success parameter and then look up some error code.

Why create Yet Another Interface when one already exists?

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
Neil McGuigan
  • 1,393
  • 2
  • 9
  • 15
  • 4
    *"Why create Yet Another Interface when one already exists?"* .. Perhaps because his application requires something beyond GET, POST, DELETE, and PUT? Why adhere to a standard that isnt a good fit for what he's doing? – GrandmasterB Jul 24 '13 at 21:01
  • I was initially thinking of doing a strict RESTful interface but I have a lot of methods like LIST, COPY, MOVE, SHARE, TAG, etc (its a cloud file system) which I found increasingly difficult to maintain within the standard HTTP methods. I know I can implement LIST as GET, and COPY, MOVE, SHARE as POST, and so on but it didn't seem to be strictly conforming to REST. My main problem now is that when I ask for client development, what do I tell them when I say "The system provides a X API" - where X could be REST, SOAP, JSON-RPC, or something else. – Jit B Jul 24 '13 at 23:11
  • _"You can probably do everything in REST that you can do in RPC"_ -- to be a bit pedantic, but REST as it is frequently implemented is a type of RPC, because the request is forwarded to a specific handler function ("procedure"). – ikh Jul 25 '13 at 01:56
  • 1
    @JitB and why not - look at SMTP as an example, it is extremely similar to REST in that it uses a " " mechanism, yet those verbs are things like MAIL or RCPT etc. Personally, I don't get hung up on whether something can only be REST if it uses the 4 magic verbs. RESTful is as good as the same thing as REST IMHO, and I'd happily use it to describe the protocol you have. – gbjbaanb Jul 25 '13 at 08:26
  • +1 @gbjbaanb for "the 4 magic verbs". The more I research RESTful API's the more I start to see religious fundamentalism lurking within the faithful. – AJB Sep 01 '13 at 22:13