148
E. Fraccaroli and D. Quaglia
The response can confirm that some alteration has been made to the stored resource,
and the response can provide hypertext links to other related resources or collections
of resources.
It the very common case in which HTTP/HTTPS is used, the REST operations
are mapped onto HTTP methods [79] as follows:
• GET method. It is used to read a representation of a resource. If the path is
correct, GET returns a representation in XML or JSON and an HTTP response
code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND)
or 400 (BAD REQUEST). According to the design of the HTTP specification,
GET (along with HEAD) requests are used only to read data and not change it.
Therefore, when used this way, they are considered safe, i.e., they can be called
without risk of data modification or corruption. Additionally, GET (and HEAD)
is idempotent, which means that making multiple successive identical requests
ends up having the same result as a single request.
• POST method. It is most often utilized to create new resources. In particular, it is
used to create subordinate resources, i.e., subordinate to some other (e.g., parent)
resource. In other words, when creating a new resource, POST to the parent and
the service takes care of associating the new resource with the parent, assigning
an ID (new resource URI). On successful creation, return HTTP status 201,
returning a Location header with a link to the newly created resource with the 201
HTTP status. POST is neither safe nor idempotent. It is therefore recommended
for non-idempotent resource requests. Making two identical POST requests will
most likely result in two resources containing the same information.
• PUT method. It is most often utilized to update capabilities, i.e., to put to
a known resource URI with the request body containing the newly updated
representation of the original resource. However, PUT can also be used to create a
resource in the case where the resource ID is chosen by the client instead of by the
server, i.e., if the PUT is to a URI that contains the value of a nonexistent resource
ID. Again, the request body contains a resource representation. On successful
update, PUT call returns 200 (or 204 if not returning any content in the body). If
PUT is used to create, it returns HTTP status 201 on successful creation. A body
in the response is optional and a waste of bytes since the client already knows the
resource ID. PUT is not a safe operation, in that it modifies (or creates) state on
the server, but it is idempotent. In other words, if you create or update a resource
using PUT and then make that same call again, the resource is still there and still
has the same state as it did with the first call. It is recommended to keep PUT
requests idempotent and to use POST for non-idempotent requests.
• PATCH method. It is used to modify capabilities. The PATCH request only
needs to contain the changes to the resource, not the complete resource. This
resembles PUT, but the body contains a set of instructions describing how a
resource currently residing on the server should be modified to produce a new
version. This means that the PATCH body should not just be a modified part
of the resource but in some patch languages like JSON Patch or XML Patch.
PATCH is neither safe nor idempotent. However, a PATCH request can be issued
E. Fraccaroli and D. Quaglia
The response can confirm that some alteration has been made to the stored resource,
and the response can provide hypertext links to other related resources or collections
of resources.
It the very common case in which HTTP/HTTPS is used, the REST operations
are mapped onto HTTP methods [79] as follows:
• GET method. It is used to read a representation of a resource. If the path is
correct, GET returns a representation in XML or JSON and an HTTP response
code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND)
or 400 (BAD REQUEST). According to the design of the HTTP specification,
GET (along with HEAD) requests are used only to read data and not change it.
Therefore, when used this way, they are considered safe, i.e., they can be called
without risk of data modification or corruption. Additionally, GET (and HEAD)
is idempotent, which means that making multiple successive identical requests
ends up having the same result as a single request.
• POST method. It is most often utilized to create new resources. In particular, it is
used to create subordinate resources, i.e., subordinate to some other (e.g., parent)
resource. In other words, when creating a new resource, POST to the parent and
the service takes care of associating the new resource with the parent, assigning
an ID (new resource URI). On successful creation, return HTTP status 201,
returning a Location header with a link to the newly created resource with the 201
HTTP status. POST is neither safe nor idempotent. It is therefore recommended
for non-idempotent resource requests. Making two identical POST requests will
most likely result in two resources containing the same information.
• PUT method. It is most often utilized to update capabilities, i.e., to put to
a known resource URI with the request body containing the newly updated
representation of the original resource. However, PUT can also be used to create a
resource in the case where the resource ID is chosen by the client instead of by the
server, i.e., if the PUT is to a URI that contains the value of a nonexistent resource
ID. Again, the request body contains a resource representation. On successful
update, PUT call returns 200 (or 204 if not returning any content in the body). If
PUT is used to create, it returns HTTP status 201 on successful creation. A body
in the response is optional and a waste of bytes since the client already knows the
resource ID. PUT is not a safe operation, in that it modifies (or creates) state on
the server, but it is idempotent. In other words, if you create or update a resource
using PUT and then make that same call again, the resource is still there and still
has the same state as it did with the first call. It is recommended to keep PUT
requests idempotent and to use POST for non-idempotent requests.
• PATCH method. It is used to modify capabilities. The PATCH request only
needs to contain the changes to the resource, not the complete resource. This
resembles PUT, but the body contains a set of instructions describing how a
resource currently residing on the server should be modified to produce a new
version. This means that the PATCH body should not just be a modified part
of the resource but in some patch languages like JSON Patch or XML Patch.
PATCH is neither safe nor idempotent. However, a PATCH request can be issued