Different HTTP methods : Ideal Use Cases

You can find assertions on the web that say

• POST should be used to create a resource, and PUT should be used to modify one
• PUT should be used to create a resource, and POST should be used to modify one

Neither is quite right.

Better is to choose between PUT and POST based on idempotence of the action.


PUT implies putting a resource - completely replacing whatever is available at the given URL with a different thing. By definition, a PUT is idempotent. Do it as many times as you like, and the result is the same. x=5 is idempotent. You can PUT a resource whether it previously exists, or not (eg, to Create, or to Update)!

POST updates a resource, adds a subsidiary resource, or causes a change. A POST is not idempotent, in the way that x++ is not idempotent.

Some APIs like twitter follow rule : Idempotence is not about always returning the same result each time (ex: Twitter).  it just means that issuing the same request multiple times won't produce additional side effects.

By this argument, PUT is for creating when you know the URL of the thing you will create. POST can be used to create when you know the URL of the "factory" or manager for the category of things you want to create.
so: POST /students
or: PUT  /students/10929


When you use POST you are always refering to a collection, so whenever you say:
               POST /students HTTP/1.1
you are posting a new user to the users collection.

If you go on and try something like this:
              POST /students/john HTTP/1.1
It will work, but semantically you are saying that you want to add a resource to the john collection under the students collection.

PATCH vs PUT

The PATCH method is the correct choice when you're updating an existing resource - with few properties. PUT should only be used if you're replacing a resource in it's entirety

 In summary

• POST to a URL creates a child resource at a server defined URL.
• PUT to a URL creates/replaces the resource in its entirety at the client defined URL.Generally used when id is known.
• PATCH to a URL updates part of the resource at that client defined URL.

For UPSERT operation
one should use PUT

DELETE : It can return the following

●  200 OK, if the resource is deleted successfully and there is something to tell the client.
●  202 Accepted, if the request is accepted but not deleted yet. This response should include some indications. Kind of batch delay , or if deletion takes time or resource marked for deletion and actual deletion happens later...
●  204 No Content,  if the resource is deleted successfully and there is nothing to tell the client.
●  in subsequent following ‘delete’ request return  404 , if resource doesn’t exists and it’s already deleted.

REST API : Using the Correct Return Types

What should DELETE return ?
Depending on the case can return following.

• 200 OK, if the resource is deleted successfully and there is something to tell the client.
• 202 Accepted, if the request is accepted but not deleted yet. This response should include some indications. Kind of batch delay , or if deletion takes time or resource marked for deletion and actual deletion happens later...
• 204 No Content,  if the resource is deleted successfully and there is nothing to tell the client.

• In subsequent following ‘delete’ request return  404 , if resource doesn’t exists and it’s already deleted …. Idempotence is not about always returning the same result each time (I'm looking at you Twitter).  it just means that issuing the same request multiple times won't produce additional side effects  

What should PUT return ?

The HTTP specification (RFC 2616) has a number of recommendations that are applicable. Here is my interpretation:

• HTTP status code 200 OK for a successful PUT of an update to an existing resource. No response body needed. (Per Section 9.6, 204 No Content is even more appropriate.)
• HTTP status code 201 Created for a successful PUT of a new resource, with the most specific URI for the new resource returned in the Location header field and any other relevant URIs and metadata of the resource echoed in the response body. (RFC 2616 Section 10.2.2)
• HTTP status code 409 Conflict for a PUT that is unsuccessful due to a 3rd-party modification, with a list of differences between the attempted update and the current resource in the response body. (RFC 2616 Section 10.4.10)
• HTTP status code 400 Bad Request for an unsuccessful PUT, with natural-language text (such as English) in the response body that explains why the PUT failed. (RFC 2616 Section 10.4)
  
  

What can POST return

• 201 : for immediate successful creation. Body has the unique if of created entity.
• 202 : if request to create is taken successfully, but creation is not complete yet.
• 500 : server side error in creation.

 Following Flow Diagram can be useful

SOAP Vs REST : Making the Right choice

SOAP Vs REST

Often the question arises which one is better and which one should be used ? Here i attempt to answer the same

Difference

	REST	SOAP
Basics	Exposes Resources which represents data	Exposes operations which exposes logic
Http Method	Uses HTTP verbs like GET / POST / DELETE	Uses HTTP Post (can't use Get) or any other protocol like smtp , ftp
Emphasis	Emphasis on simple point to point communication using HTTP.	Emphasis on loosely coupled distributed messaging.
Data Formats	Supports multiple data formats like XML , JSON	Supports only xml.
Stateless vs Stateful	Emphasizes stateless communication	Supports stateless and stateful  conversation and operations
Caching	Since HTTP based / Rest-ful APIs can be consumed using simple GET requests, intermediate proxy servers / reverse-proxies can cache their response very easily	SOAP requests use POST and require a complex XML request to be created which makes response-caching difficult. Depending on protocol used may be more tough to cache.
Testing	It is also easy to test and troubleshoot an HTTP API since one can construct a call with nothing more than a browser and check the response inside the browser window itself.	There are special tools (SOAPUI) & libraries to test SOAP services hence a learning curve.
2 Phase commit	REST is limited by HTTP itself which can’t provide two-phase commit across distributed transactional resources	SOAP can. ( hence better choice for enterperise services )
Full form	REST (Representational State Transfer)	SOAP (Simple Object Access Protocol)
		Supports asynchronous messaging
		Strong typing, it has a fixed set of supported data types
	Can easily do CRUD operations

When is REST Better than SOAP

1. REST can be consumed by any client even a web browser with ajax and JavaScript.
2. Rest is light weight
1. Doesn't require xml parsing
2. consumes less bandwidth - doesnt require a soap header for every msg
3. REST is safe
1. supports HTTPs
2. -  aren't GET operations safe ? ( but they do expose params in url )

When is SOAP Better than REST

1. Building a client for REST can be challenging
1.   for soap can generate clients for wsdl
2. dont have to write raw http calls
3. SOAP can use own java exceptions , in REST look at the http response code
2. REST only supports HTTP / HTTPs
3. Parameter of REST will be exposed as a part of URI ( may be a security consideration ) 
4. REST doesnt support reliable messaging 
5. REST cannot be governed
1.  how do i know who is consuming my WS w/o registry
2.  how to discover a Restful WS

Good places to use REST

1. Limited bandwidth
2. Limited resources
3. when ok to Expose URL data on web
4. Combining content from many different sources on web ( mashups )

Good places to use SOAP

1. Enterprise Services
1. high reliability WS-RM :- Rest doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying. SOAP has successful/retry logic built in and provides end-to-end reliability even through SOAP intermediaries.
2. Transactions with WS-AT    :- Need ACID Transactions over a service, you’re going to need SOAP. While REST supports transactions, it isn’t as comprehensive and isn’t ACID compliant. 
3. Security with WS-Security , adds enterprise level security , Supports identity through intermediaries, not just point to point . It also provides a standard implementation of data integrity and data privacy. 
2. Asynchronous processing
3. Stateful operation
4. standard support interoperability with Buss apps
5. Tooling support

Code Example And Performance

http://livoris.de/node/16

The above article gives simple code example and performance analysis for both

SOAP Disadvantages

1. Main use of SOAP is RPC ( generate proxy and use it to RPC ) but its not easy to pass even integers across two platforms

2. Strong typing is a bad choice for loosely coupled distributed systems. The moment you need to change anything, the type signature changes and all the clients that were built to your earlier protocol spec break.