Representational state transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation.
Safety
An HTTP method is said to be safe if it does not change the state of a resource when invoked. GET and HEAD methods are safe, they retrieve data and no matter how many times they are called the state of the resource is not changed. POST is sometimes safe if it is used to retrieve data and does not create or update. Some purest may say that POST should only be used to create a resource, but in many real-world implementations you will see form POST used for complex queries or data retrieval.
Idempotent
An HTTP method is idempotent if it can be called multiple times and the end result is the same. GET, HEAD, PUT and DELETE methods are idempotent; they can be called any number of times with the same result. Some will argue that DELETE is not idempotent because the second, third, etc. calls can result in an error message, but there are no side-effects to the resource so it is idempotent.[1]
HTTP Methods
| HTTP VERB | Description | Response Code | Note |
|---|---|---|---|
| GET | Retrieve | 200 : OK | Code returned in header, data returned in body (bytestream). Idempotent, Safe, linkable, cacheable |
| POST | Create | 201 : CREATED | Optionally return with a location (URI) of the newly created resource |
| PUT | Update | 200 : OK, 202 : ACCEPTED, 204 : NO_CONTENT |
Not supported by browsers. Idempotent |
| DELETE | Delete | 200 : OK, 202 : ACCEPTED, 204 : NO_CONTENT |
Not supported by browsers. Idempotent |
| HEAD | Retrieve | 200 : OK | HEAD is similar to GET. The significant difference is that the representation is not returned. Rather, only the HTTP header with the various headers is returned. Idempotent, Safe |
| OPTIONS | API description | 200 : OK | Self describing API |
| PATCH | Patch | 200 : OK, 202 : ACCEPTED, 204 : NO_CONTENT |
Partial updates, Not supported by browsers. |
| TRACE | Trace | 200 : OK | The TRACE method is used to invoke a remote, application-layer loop-back of the request message. Used for testing. |
HTTP Response codes
| CODE | Constant | Description |
|---|---|---|
| 200 | OK | Successfully executed |
| 201 | CREATED | Successfully executed and a new resources has been created. The response body is either empty or contains a URI(s) of the created resource. The location header should should also contain the new URI |
| 202 | ACCEPTED | The request was valid and has been accepted but has not yet been processed. The response should include a URI to poll for status updates on the request. Allows for asynchronous request |
| 204 | NO_CONTENT | The request was successful but the server did not have a response |
| 301 | MOVED_PERMANENTLY | The new location should be returned in the response |
| 400 | BAD_REQUEST | Malformed or invalid request |
| 401 | UNAUTHORIZED | Invalid authorization credentials |
| 403 | FORBIDDEN | Disallowed request. Security error |
| 404 | NOT_FOUND | Resource not found |
| 405 | METHOD_NOT_ALLOWED | Method (verb) not allowed for requested resource. Response will provide an “Allow” header to indicate what is allowed |
| 415 | UNSUPPORTED_MEDIA_TYPE | Client submitted a media type that is incompatible for the specified resource. |
| 500 | INTERNAL_SERVER_ERROR | Catchall for server processing problem |
| 503 | SERVICE_UNAVAILABLE | Response in the face of too many request |
John Deringer 