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?
7
There are really two definitions of REST:
-
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. -
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.
5
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.
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?
5