Editing REST (section)

==Principles==

* The state of a resource remains internal to the server, not the client – The client can request it, or update it with requests made to the server.
* No client context saved on the server between requests – The server must not store the status of a client. Otherwise, this would break the scalability objective of REST when reaching a couple million users. Remember that requests can be distributed to several physical servers, which could cause physical resource consumption issues.
* Client requests contain all information to service it – No matter which request is sent by a client to a server, it must be complete enough for the server to process it.
* Session states are stored on the client side – If necessary, any information about the status of the communication between a logical server and a logical client must be held on the client side.
* Multiple representations of a resource can coexist – The chosen format used to represent the state of a resource in requests and responses is free (XML, JSON…). Multiple formats can be used.
* Responses explicitly indicate their cacheability – When a server returns a response to a request, the information it contains may or may not be cached by the client. If not, the client should make new requests to obtain the latest status of a resource, for example.
* Code on Demand – This is an optional feature in REST. Clients can fetch some extra code from the server to enrich their functionalities. An example is Javascript.
* send the right response, e.g. CREATE return code instead of SUCCESS code

There is a discussion ongoing which HTTP message type should be used for which actions. E.G. see [http://restcookbook.com/HTTP%20Methods/put-vs-post/ here] (see corresponding [[#Annotations|annotations]] below):
*Use PUT to UPDATE data
*Use POST to ADD data
*Use DELETE to REMOVE data
*Use GET to RETREIVE data

Sometimes there is a recommendation to use the PATCH message if parts are updated.

Another explanation is: choose between PUT and POST based on idempotence of the action. Idempotence means that calling the API multiple times it should be as a single modification, wheras Non-Idempotence means calling an API multiple times results in multiple resources.

so:
 POST /expense-report

or:
 PUT  /expense-report/10929

Web Application Description Language (WADL) is a machine-readable description of HTTP based REST web services, but is not popular. An alternative is Swagger.