REST is a set of architectural principles that can be used to design Web services focused on the system’s resources. This includes how resource states are handled and transferred over HTTP by clients writing in different languages. Based on the number of Web services REST uses, it has been the dominant Web service design model for the past few years. Because REST is so simple to use, it has significantly impacted the Web.
When REST was introduced at the University of California in Irvine in 2000, Roy Fielding’s academic dissertation “Architectural Styles & the Design of Networked Software Architectures” didn’t draw much attention. It is a collection of software architecture principles that uses the Web to facilitate distributed computing. Major frameworks for REST are now being developed many years after it was first introduced.
This article suggests that, in its purest form, when it is attracting so much attention, a concrete implementation of a REST Webservice follows four basic design principles.
Use HTTP methods explicitly.
Do not be stateless
Expose directory structure-like URIs.
Transfer XML or JavaScript Object Notation JSON, or both.
These four principles are outlined in the following sections. They also provide technical reasons why they may be of value to REST Web service developers.
Use HTTP methods explicitly
A RESTful Web Service must explicitly use HTTP methods by RFC 2616. HTTP GET is a data-producing method that can be used by client applications to retrieve a resource or fetch data from a Webserver. It also allows the user to ask the Web server for matching resources.
REST requires developers to use HTTP methods consistent with the protocol definition. This is the basic REST design principle. It establishes a one-to-one mapping of create, read (update, delete) operations and HTTP methods. This mapping is:
Use POST to create a resource on your server.
Use GET to retrieve a resource.
Use PUT to change the state or update a resource.
To remove or delete a resource, use DELETE.
Unintended uses of HTTP methods are a common design flaw in many Web APIs. For example, the request URI for an HTTP GET request usually identifies a specific resource. The query string of a request URI also includes a list of parameters that define the search criteria used to locate matching resources. This is the HTTP/1.1 RFC’s description of GET. There are many unattractive Web APIs, however. These use HTTP GET to trigger a transaction on the server. For instance, to add records to a database. In these cases, the GET request URI does not get used correctly or RESTfully used. It looks like this if the Web API uses GET for remote procedures:
This design could be more attractive, as the Web method above supports state-changing operations over HTTP GET. The HTTP GET request above can have side effects. In this case, the request will be processed successfully, and add Robert to the underlying data storage. This is where the problem lies. Web servers are intended to respond to HTTP GET queries by retrieving resources that match their query criteria or path. They return these, or a representation in a reply, and do not add a record to a table. This needs to be more consistent from both the point of view of the intended use and the HTTP/1.1-compliant Web server perspective.
Beyond semantics, GET can also trigger deletion, modification, or addition of records in a database or server-side status changes. This invites Web crawlers and search engines to make unintentional server-side changes by simply crawling a link. This common problem can be overcome by merely converting the parameter names and values from the request URI to XML tags. The resulting tags, an XML representation for the entity to be created, can be sent in an HTTP POST body whose request URI corresponds with the entity’s intended parent.
This is an example of a RESTful Request. It uses HTTP POST properly and includes the payload in its body. The request can be processed on the receiving end by adding the resource in the body to the resource identified in the request URI. The new resource should also be counted as a child /user in this case. The POST request specifies that the new entity must be contained with its parent. This is similar to how a file is subordinated to its parent directory. The client creates the relationship between the entity and its parent and specifies the new entity’s URL in the POST request.
This will change the property (or name) of the resource. While the query string can be used for such an operation, and Listing four is simple, this query-string-as-method-signature pattern tends to break down when used for more complex procedures. For the same reasons as above, you should send an HTTP PUT request to update a resource. This is because your goal is to use HTTP methods explicitly.
Using PUT to replace an original resource creates a cleaner interface consistent with REST principles and the definitions of HTTP methods. Listing 5’s PUT request explicitly points to the updated resource by identifying it in a request URI. It also transfers a new representation from the client to the server in a PUT response instead of sharing resource attributes as a loose collection of parameter names and values to the request URL. Listing 5 has the effect of changing the resource’s URI from Robert and Bob. A REST Web service will return a standard 404 Not Found error if the help is reaccessed using the same URI.
It is a good design principle to use HTTP methods explicitly. This can be done by using nouns rather than verbs in URIs. The protocol already defines the verbs POST, GET and PUT in a RESTful Webservice. To keep the interface simple and allow clients to be more specific about the operations they invoke, the Web services should not include auxiliary verbs or remote procedures such as /add user or/update user. This design principle applies to an HTTP request body. It is not intended to contain the name of a remote method or procedure, but it does serve to transfer resource state.