HTTP method+status code combos and their (http) meaning.

Hi All,

I've taken some time to document all the valid combinations of HTTP 
methods & status codes, taking in to account Content-Location with 
differing values - what you can determine from these messages, and 
also the state of each resource in relation to each combination of 
method and status code.

As follows:

==============

Which status codes can each method use?

	200	201	202	203	204	205	206	304
GET	x			x			x	x
HEAD	x			x			x	x
POST	x	x	x		x	x	
PUT	x	x			x		
DELETE	x		x		x		

==============

Combinations which always return a resource representation:

	200	201	202	203	204	205	206	304
GET	f			f	m		p	m
HEAD	m			m	m		p	m
POST								
PUT								
DELETE								

key: f = full, m = meta only, p = partial
note: I can't see any situation where you'd use GET or HEAD with 204 
No Content, but, it's valid.

==============

Combinations which return a resource representation of the resource 
identified by the effective request URI, if the Content-Location 
*matches* the effective request URI:

	200	201	202	203	204	205	206	304
GET	f			f			p	m
HEAD	m			m			p	m
POST	f							
PUT	f	f			m			
DELETE								

==============

Combinations which return a resource representation of the resource 
identified by the effective request URI, if the Content-Location *is 
different from* the effective request URI:

	200	201	202	203	204	205	206	304
GET	f			f			p	m
HEAD	m			m			p	m
POST								
PUT								
DELETE								

note: this case is an important one, the resource representation 
returned is a representation of /both/ the resource identified by the 
effective request URI /and/ the resource identified by the 
Content-Location value - typically utilized by server driven negotation.

==============

Combinations which *do not* return a resource representation of the 
resource identified by the effective request URI, but /do/ return a 
resource representation of some other resource identified by the 
Content-Location (Content-Location does not match effective request URI):

	200	201	202	203	204	205	206	304
GET								
HEAD								
POST	f		f					
PUT	f	f						
DELETE	f		f					

note: this case typically covers a message representation in response 
to a request, that can be accessed "later" by the client using the URI 
given by the Content-Location.

==============

Special Case, if the response to a POST is 201 Created, and the 
Content-Location header value matches the Location header value, then 
the representation is a resource representation of the (newly created) 
resource identified by the URI given in the Content-Location+Location.

==============

Combinations where the representation is of an unknown resource (no 
Content-Location is given):

	200	201	202	203	204	205	206	304
GET								
HEAD								
POST	x	x	x					
PUT	x	x						
DELETE	x		x					

note: this case typically covers "normal" status messages such as 
"okay it's been deleted" or "okay it's been created", most common case 
being the response to a POST.

==============

Target resource state
By analysing the combinations of status code and method, one can 
determine the current state of the target resource (that identified by 
the effective request URI).

The possible states of a resource are:
- s, the initial state, created
- n, the current state (or simply, you know the resource exists)
- n+1, the state has just changed
- f, the final "gone" state, resource did exist, but no longer exists
- u, the unknown state (no idea if the resource exists or not)

Here's how it maps out for 2xx status code and method combinations:

	200	201	202	203	204	205	206
GET	n			n			n
HEAD	n			n			n
POST	n*	n	n		n	n	
PUT	N+1	s			N+1		
DELETE	f		u		f		

n*: if POST 200 and Content-Location == effective request URI then the 
state is N+1 (just changed state)

Here's a guess at the 3xx status codes, it's currently unclear to me 
whether a typical "redirect" (300/301/2/7) indicates that the resource 
exists or not, as a subsequent request on the URI given by the 
Location could be an unknown state (404 for instance), however in the 
case of 301/2/7 the server could remove the temporary redirect and 
you'd then know the resource still existed. These are all marked with 
n?, may have to change to u.

	300	301	302	303	304	307
GET	n?	n?	n?	u	n	n?
HEAD	n?	n?	n?	u	n	n?
POST		n?	n?	u		n?
PUT		u				
DELETE						

The 4xx class of status codes are much harder to classify than you'd 
think, with the exception of 410 Gone which indicates the resource no 
longer exists (f).

	400	401	402	403	404	405	406	407
GET	u	?		u	u	n?	n	?
HEAD	u	?		u	u	n?	n	?
POST	u	?		u	u	n?	?	?
PUT	u	?		u	u	u	?	?
DELETE	u	?		u	u	u	?	?

	408	409	410	411	412	413	414	415
GET	u	?	f		n		u	
HEAD	u	?	f		n		u	
POST	u	?	f	u	?	u	u	u
PUT	u	u	f	u	n	u	u	u
DELETE	u	u	f		n		u	

	416	417
GET	n	u
HEAD	n	u
POST		u
PUT	?	u
DELETE	?	u

note: where there's a space, this indicates that the status code / 
method combination is invalid, undefined, or makes no sense. For 
instance 411 Length Required can only be used with methods that accept 
a message body (POST/PUT), 402 Payment Required is undefined, and 416 
Requested Range Not Satisfiable makes no sense with POST, and with 
PUT/DELETE would indicate you replace or remove ranges from a 
representation / resource.

The 5xx all indicate the unknown state, u.

note: all of this has been calculated from the HTTPbis spec, draft 12.

Best & hope that's useful in some way,

Nathan

Received on Monday, 24 January 2011 12:03:46 UTC