The REST Conductor
Improper REST usage is difficult to scale and can reduce developer adoption. The following points are important to consider when taking on the role as The REST Conductor.
REST is an ideal solution for data collections and underlying data:
- For all data resources the common HTTP 1/1 verbs are used to specify the action taken on the resources GET, PUT POST and DELETE.
- All resource names should be plural nouns.
- The resource path should be resource restrictive. If a word is in the path of the URI, the word should return a value.
- Collections should be returned for the plural connotation, e.g. “Devices.”
- To refer to a specific resource, the ID of the resource should be used, e.g. “/Devices/4893”.
- An operation is idempotent if a sequence of two or more of the same operations results in the same state or result. (If you call an operation more than once you should receive the same result.) According to the HTTP 1.1 specification, GET, HEAD, PUT, and DELETE are idempotent, while POST is not. Multiple attempts to PUT (update) data to a URL results in the same resource state returned, which is the same as a single attempt to PUT data to the URL. However, the same cannot be said of a POST request as the state of the resource may change.)
- The following is recommended for REST operations:
- Create = PUT if and only if you are sending the full content of the specified resource (URL).
- Create = POST if and only if you are sending a command to the server to create a subordinate of the specified resource, using some server-side algorithm.
- Retrieve = GET (must be side effect free).
- Update = PUT if and only if you are updating the full content of the specified resource.
- Update = POST if and only if you are requesting the server to update one or more subordinates of the specified resource.
- Delete = DELETE.
- REST resources may put hyperlinks within URI representation to enable clients to drill down for more information, and/or to obtain related information. Moreover, REST resources may gradually reveal data rather than in a single response document by providing hyperlinks to obtain more details.