+ Below is a more-detailed discussion of the main HTTP methods. Click on a tab for more information about the desired HTTP method.
The POST verb is most-often utilized to **create** new resources. In particular, it's used to create subordinate resources. That is, 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), etc.
+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.
+Examples:
+-
+
- POST http://www.example.com/customers +
- POST http://www.example.com/customers/12345/orders +
The HTTP GET method is used to retrieve (or read) a representation of a resource. In the “happy” (or non-error) path, 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).
+The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, 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. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
Do not expose unsafe operations via GET—it should never modify any resources on the server.
Examples:
@@ -109,7 +124,7 @@PUT is most-often utilized for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.
+PUT is most-often utilized for **update** capabilities, PUT-ing 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. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all.
Alternatively, use POST to create new resources and provide the client-defined ID in the body representation—presumably to a URI that doesn't include the ID of the resource (see POST below).
On successful update, return 200 (or 204 if not returning any content in the body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation. A body in the response is optional—providing one consumes more bandwidth. It is not necessary to return a link via a Location header in the creation case since the client already set the resource ID.
@@ -122,18 +137,8 @@The POST verb is most-often utilized for creation of new resources. In particular, it's used to create subordinate resources. That is, 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), etc.
-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.
-Examples:
--
-
- POST http://www.example.com/customers -
- POST http://www.example.com/customers/12345/orders -
DELETE is pretty easy to understand. It is used to delete a resource identified by a URI. +
DELETE is pretty easy to understand. It is used to **delete** a resource identified by a URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within the resource), the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource requests is recommended.
There is a caveat about DELETE idempotence, however. Calling DELETE on a resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
diff --git a/lessons/restfulresourcenaming.html b/lessons/restfulresourcenaming.html index 27e4a33..f11d896 100644 --- a/lessons/restfulresourcenaming.html +++ b/lessons/restfulresourcenaming.html @@ -53,7 +53,7 @@In addition to utilizing the HTTP verbs appropriately, resource naming is arguably the most debated and most important concept to grasp when creating an understandable, easily leveraged Web service API. When resources are named well, an API is intuitive and easy to use. Done poorly, that same API can feel klutzy and be difficult to use and understand. Below are a few tips to get you going when creating the resource URIs for your new API.
-Essentially, a RESTFul API ends up being simply a collection of URIs, HTTP calls to those URIs and some JSON and/or XML representations of resources, many of which will contain relational links. The RESTful principal of addressability is covered by the URIs. Each resource has its own address or URI—every interesting piece of information the server can provide is exposed as a resource. The constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs, and using them in line with the standards and conventions.
+Essentially, a RESTful API ends up being simply a collection of URIs, HTTP calls to those URIs and some JSON and/or XML representations of resources, many of which will contain relational links. The RESTful principal of addressability is covered by the URIs. Each resource has its own address or URI—every interesting piece of information the server can provide is exposed as a resource. The constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs, and using them in line with the standards and conventions.
In deciding what resources are within your system, name them as nouns as opposed to verbs or actions. In other words, a RESTful URI should refer to a resource that is a thing instead of referring to an action. Nouns have properties as verbs do not, just another distinguishing factor.
Some example resources are:
-
diff --git a/lessons/restquicktips.html b/lessons/restquicktips.html
index 32ec82e..0b625ff 100644
--- a/lessons/restquicktips.html
+++ b/lessons/restquicktips.html
@@ -111,7 +111,7 @@
- PDF (~306KB)
- ePub (~46KB). Works on iPad, iPhone, B&N Nook and most other readers. diff --git a/sitemap.xml b/sitemap.xml index 15d3170..6300491 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -22,7 +22,7 @@
Offer Both JSON and XML
-Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, Schema validation and namespaces. And offer both JSON and XML unless the costs are staggering. Ideally, let consumers switch between using the HTTP Accept header, or by just changing an extension from .xml to .json on the URL.
+Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, Schema validation and namespaces. And offer both JSON and XML unless the costs are staggering. Ideally, let consumers switch between formats using the HTTP Accept header, or by just changing an extension from .xml to .json on the URL.
Be warned though, as soon as we start talking about XML support, we start talking about schemas for validation, namespaces, etc. Unless required by your industry, avoid supporting all that complexity initially, if ever. JSON is designed to be simple, terse and functional. Create your XML to look like that if you can.
In other words, make the XML that is returned more JSON-like: simple and easy to read, without the schema and namespace details present—just data and links. If it ends up being more complex than this, the cost of XML will be staggering. In my experience nobody uses the XML responses anyway over the last several years. It's just too expensive to consume.
Note that JSON-Schema offers schema-style validation capabilities, if you need that sort of thing.
diff --git a/resources.html b/resources.html index 2c6d976..cdcceab 100644 --- a/resources.html +++ b/resources.html @@ -37,8 +37,13 @@REST API Resources
+Translations
+RESTful Best Practices
-Get the Pearson eCollege RESTful Best Practices guide (choose your format). This guide reduces the world of RESTful services into easy-to-follow principles. It also provides several cookbook type recipes in critical areas to increase service usability, reduce confusion during implemenation, as well as improve consistency.
+Get the Pearson Higher-Education RESTful Best Practices guide (choose your format). This guide reduces the world of RESTful services into easy-to-follow principles. It also provides several cookbook type recipes in critical areas to increase service usability, reduce confusion during implemenation, as well as improve consistency.