views:

169

answers:

3

I have a REST web service which exposes 2 methods-

  1. [POST method] Client will supply a list of objects in the form of an XML. My web service method will insert/update the list of objects based on one attribute in the object [mode = insert/update], and will return an XML with the list of objects and their status[whether insert/update was successful].
  2. [POST method] It will accept a list of objectIds and return the status of these objects from the server in the form of an XML.

I know that we should use

  • GET method for retrieving information
  • POST method for creating a new entry
  • PUT method for updating an existing entry.

I know that our implementation violates some of the REST constraints but our requirement forced us to implement it that way.

My question is - Is it ok to bend the constraints to accomodate our requirement?

+1  A: 

This web service is not RESTful. You can always bend the constraints but you lose the REST label :-)

Darin Dimitrov
+1  A: 

The problem with bending the rules is that the clients consuming your web services may assume things that might not apply. In general, this is not a big problem if you own both the client and the service, but for a public web service, you may want to consider a better adhesion to the REST principles.

Daniel Vassallo
Thanks for the quick response. How do I implement the first method in a RESTful manner? One way is to make the <saveObject> call for each object [which the client doesn't want]. Is there a way we can handle multiple insert/updates in a RESTful way?
Surjit
@Surjit: You may want to check out [Darrel's answer](http://stackoverflow.com/questions/3139405/is-my-web-service-restful/3144039#3144039) regarding that.
Daniel Vassallo
+3  A: 

What you are trying to do can be done RESTfully. Although POST is commonly used to add a single entity to a collection, it can also be used to submit a chunk of data to a "data processing resource". This pretty much opens the door to do anything you want with a POST.

People frequently misunderstand the REST constraints and believe that you MUST use PUT and DELETE in order to be RESTful. This is not the case. There is no requirement to use all of the methods. The only requirement is not to misuse the ones you do use.

Obviously it is going to be more intuitive to a user of your API if you POSTed a single entity to a collection to create an entity. However, if this is not a viable option for you then you are free define a new media type that can contain a set of objects to be created/updated by some data processing resource.

The important thing is to be explicit about these rules. You should create a new media type, like application/vnd.yourcompany.objectlist+xml and you need to write documentation about how that media type should be structured.

Now that you have defined the media type your client is going to need to know where to POST that list of objects. Ideally you would define a new link relation (e.g. objectprocessor) that can be used in other documents to provide an URL to POST to. In the specification document of that Link relation you should explain to client developers, that when you post an application/vnd.yourcompany.objectlist+xml to a link that has the link relation objectprocessor then what is going to happen is x, y, and z.

Assuming your root URL returned some kind of XHTML document like:

<html>
  <h1>My awesomely restful service that can create objects in batches</h1>
  <link rel='objectprocessor' href='http:/example.org/myservice/objectprocessor'/>
</html>

A client application could process this document, discover this link and understand based on the link relation definition that it needs to POST a application/vnd.yourcompany.objectlist+xml to the endpoint specified in href.

In this way, the message is completely self-descriptive, you are interacting with resources identified with URLs that are discoverable and you are within the rules of the uniform interface.

Darrel Miller