Java – Testing REST webservices

Overall:

Both PUT and POST can be used for creating.

You have to ask, "what are you performing the action upon?", to distinguish what you should be using. Let's assume you're designing an API for asking questions. If you want to use POST, then you would do that to a list of questions. If you want to use PUT, then you would do that to a particular question.

Great, both can be used, so which one should I use in my RESTful design:

You do not need to support both PUT and POST.

Which you use is up to you. But just remember to use the right one depending on what object you are referencing in the request.

Some considerations:

• Do you name the URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.
• PUT is defined to assume idempotency, so if you PUT an object twice, it should have no additional effect. This is a nice property, so I would use PUT when possible. Just make sure that the PUT-idempotency actually is implemented correctly in the server.
• You can update or create a resource with PUT with the same object URL
• With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object.

An example:

I wrote the following as part of another answer on SO regarding this:

POST:

Used to modify and update a resource

POST /questions/<existing_question> HTTP/1.1
Host: www.example.com/

Note that the following is an error:

POST /questions/<new_question> HTTP/1.1
Host: www.example.com/

If the URL is not yet created, you should not be using POST to create it while specifying the name. This should result in a 'resource not found' error because <new_question> does not exist yet. You should PUT the <new_question> resource on the server first.

You could though do something like this to create a resources using POST:

POST /questions HTTP/1.1
Host: www.example.com/

Note that in this case the resource name is not specified, the new objects URL path would be returned to you.

PUT:

Used to create a resource, or overwrite it. While you specify the resources new URL.

For a new resource:

PUT /questions/<new_question> HTTP/1.1
Host: www.example.com/

To overwrite an existing resource:

PUT /questions/<existing_question> HTTP/1.1
Host: www.example.com/

Additionally, and a bit more concisely, RFC 7231 Section 4.3.4 PUT states (emphasis added),

4.3.4. PUT

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

REST should be used if it is very important for you to minimize the coupling between client and server components in a distributed application.

This may be the case if your server is going to be used by many different clients that you do not have control over. It may also be the case if you want to be able to update the server regularly without needing to update the client software.

I can assure you that achieving this low level of coupling is not easy to do. It is critical to follow all of the constraints of REST to succeed. Maintaining a purely stateless connection is difficult. Picking the right media-types and squeezing your data into the formats is tricky. Creating your own media types can be even harder.

Adapting rich server behaviour into the uniform HTTP interface can be confusing and at times appears pedantic in comparison to the relatively straightforward RPC approach.

Despite the difficulties, the benefits are that you have a service that a client developer should be able to easily understand due to the consistent use of the HTTP protocol. The service should be easily discoverable due to hypermedia and the client should be extremely resilient to changes on the server.

The benefits of hypermedia and the avoidance of session state makes load balancing simple and service partitioning feasible. The strict conformance to HTTP rules make the availability of tools like debuggers and caching proxies wonderful thing.

Update

It seems to me that REST is another 'last word of fashion' (or I can be totally wrong because I haven't ever seen REST in practice).

I think REST has become fashionable because people attempting to do SOA type projects have found that using the SOAP stack they are not realizing the benefits that were promised. People keep turning back to the web as an example of simple integration methodologies. Unfortunately, I think people underestimate the amount of planning and foresight that went into creating the web and they oversimplify what needs to be done to allow the kind of serendipitous reuse that does occur on the web.

You say that you have never seen REST in practice, but that cannot possibly be true if you ever use a web browser. The web browser is a REST client.

• Why do you not need to do a browser update when someone changes some html on a web site?
• Why can I add a complete new set of pages to a web site and the "client" can still access those new pages without an update?
• Why do I not need to provide a "service-description-language" to the web browser to tell it when it goes to http://example.org/images/cat that the return type will be a jpeg image and when you go to http://example.org/description/cat the return type will be text/html?
• Why can I use a web browser to visit sites that did not exist when the browser was released? How can the client know about these sites?

These may sound like inane questions, but if you know the answer, then you can start to see what REST is all about. Look at StackOverflow for more benefits of REST. When I am looking at a question, I can bookmark that page or send the url to a friend and he can see the same information. He doesn't have to navigate through the site to find that question.

StackOverflow uses a variety of OpenId services for authentication, gravatar.com for avatar images, google-analytics and Quantserve for analytical information. This kind of multi-company integration is the type of thing the SOAP world only dreams of. One of the best examples is the fact that the jQuery libraries that are used to drive the StackOverflow UI are retrieved from Google's Content Delivery Network. The fact that SO could direct the client (i.e. your web browser) to download code from a third-party site to improve performance is testament to the low coupling between web client and server.

These are examples of a REST architecture at work.

Now some web sites / applications do break the rules of REST and then the browser does not work as expected.

• The infamous back button problem is caused by using server side session state.
• Load balancing can become a pain when you have server side session state.
• Flash applications often prevent the URL from specifically identifying a representation.
• The other problem that breaks web browsers is poor conformance to media-type standards. We hear all of the time about how IE6 needs to be killed. The problem there is that standards were not properly followed, or were ignored for whatever reason.
• The use of login sessions are the source of many security holes.

REST is everywhere. It is the part of the web that makes it work well. If you want to build distributed applications that can scale like the web, be resilient to change like the web and promote re-use as the web has done, then follow the same rules they did when building web browsers.