![](https://csdnimg.cn/release/download_crawler_static/10624204/bg11.jpg)
CHAPTER 2 ■ WHAT IS RESTFUL?
13
Technically speaking, the REST architectural style is agnostic about any specific protocol. That includes the HTTP
protocol. In other words, all you need is a protocol that provides a language and mechanism for describing both states
(i.e., representations) and state changes. However, since this book is about building a REST service with the ASP.NET
Web API, you’ll focus on REST with HTTP. Fortunately, the HTTP protocol itself covers most of what you need.
Let’s walk through some important concepts with this mapping. First, the exact meaning of each of the four verbs
is dependent on the URI. So even though you have only four verbs, you actually have eight different actions available
to you. The difference lies in whether the URI defines a collection or a unique element.
Second, when creating new instances of the resource (e.g., a new task), PUT is used with a unique URI in the
scenario where the caller generates the new resource’s identifier before submitting the request to the server. In
Table 2-3, the PUT action is used with a unique element URI to create a new task with the specific identifier, 1234.
If instead the system is to generate the identifier, the caller uses the POST action and a collection URI. This also ties
into the concept of idempotency.
The GET, PUT, and DELETE methods are said to be idempotent; that is, calling them over and over will produce
the same result without any additional side effects. For example, the caller should be able to call the DELETE action
on a specific resource without receiving any errors and without harming the system. If the resource has already been
deleted, the caller should not receive an error. The same applies to the PUT action. For a given unique resource
(identified by an element URI), submitting a PUT request should update the resource if it already exists. Or, if it
doesn’t exist, the system should create the resource as submitted. In other words, calling PUT over and over produces
the same result without any additional side effects (i.e., the new task will exist in the system per the representation
provided by the caller, whether the system had to create a new one or update an existing one).
The GET action is also said to be safe. Safe means that nothing in the system is changed at all, which is appropriate
for HTTP calls that are meant to query the system for either a collection of resources or for a specific resource.
It is important that the idempotency of the service’s GET, PUT, and DELETE operations remain consistent with
the HTTP protocol standards. Thus, every effort should be made to ensure those three actions can be called over and
over without error.
Unlike the other three actions, POST is not considered to be idempotent. This is because POST is used to create
a new instance of the identified resource type for every invocation of the method. Where calling PUT over and
over will never result in more than one resource being created or updated, calling POST will result in new resource
instances—one for each call. This is appropriate for cases where the system must generate the new resource’s
identifier and return it in the response.
As you model your task-management service, you will need to map each resource with a set of HTTP actions,
defining which ones are allowed and which ones aren’t supported.
Now let’s take a new look at the task service. This time around, you’ll use the available HTTP verbs, which will put
you at level 2 on the RMM. (See Table 2-4.)
Table 2-3. Using HTTP Verbs with the Task Resource
HTTP verb (Collection URI)
http://myserver.com/tasks
(Element URI)
http://myserver.com/tasks/1234
GET List of tasks, including URIs to individual tasks Get a specific task, identified by the URI
PUT Replace the entire collection of tasks Replace or create the single task identified
by the URI
POST Create a new single task, where its identifier is
generated by the system
Create a new subordinate under the task
identified by the URI
DELETE Delete the entire collection of tasks Delete the tasks identified by the URI