TheCloneArmy/RestApiGuide
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Refactored menu structure to introduce lessons drop-down.

Browse Source
This commit is contained in:
Todd Fredrich
2012-06-14 08:12:19 -06:00
parent 277b95e732
commit 98217e8d8c
7 changed files with 170 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
lessons/httpmethods.html Normal file
View File

@ -0,0 +1,176 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>HTTP Methods for RESTful Services</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="HTTP methods tutorial on how to use them for RESTful API or Web Service.">
<meta name="author" content="Todd Fredrich, Pearson eCollege">
<!-- Le styles -->
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap.min.css" rel="stylesheet">
<style type="text/css">
body {
padding-top: 60px;
padding-bottom: 40px;
}
</style>
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap-responsive.min.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="//html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-31328878-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="container">
<div class="row">
<div class="span12">
<h1>Using HTTP Methods for RESTful Services</h1>
<p>The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods, OPTIONS and HEAD are used more often than others.</p>
</div>
</div>
<div class="row">
<div class="span12">
<p>Below is a table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:</p>
<table class="table table-striped table-bordered">
<thead>
<tr>
<th>HTTP Verb</th>
<th>Entire Collection (e.g. /customers)</th>
<th>Specific Item (e.g. /customers/{id})</th>
</tr>
</thead>
<tbody>
<tr>
<td>GET</td>
<td>200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.</td>
<td>200 (OK), single customer. 404 (Not Found), if ID not found or invalid.</td>
</tr>
<tr>
<td>PUT</td>
<td>404 (Not Found), unless you want to update/replace every resource in the entire collection.</td>
<td>200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.</td>
</tr>
<tr>
<td>POST</td>
<td>201 (Created), 'Location' header with link to /customers/{id} containing new ID.</td>
<td>404 (Not Found).</td>
</tr>
<tr>
<td>DELETE</td>
<td>404 (Not Found), unless you want to delete the whole collection—not often desirable.</td>
<td>200 (OK). 404 (Not Found), if ID not found or invalid.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="row">
<div class="span12">
<p>Below is a more-detailed discussion of the main HTTP methods. Click on a tab for more information about the desired HTTP method.</p>
<ul class="nav nav-tabs">
<li class="active"><a href="#get" data-toggle="tab">GET</a></li>
<li><a href="#put" data-toggle="tab">PUT</a></li>
<li><a href="#post" data-toggle="tab">POST</a></li>
<li><a href="#delete" data-toggle="tab">DELETE</a></li>
</ul>
<div id="methodTabContent" class="tab-content">
<div class="tab-pane fade in active" id="get">
<p>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).</p>
<p>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.</p>
<p>Do not expose unsafe operations via GET—it should never modify any resources on the server.</p>
<p><strong>Examples:</strong></p>
<ul>
<li><em>GET http://www.example.com/customers/12345</em></li>
<li><em>GET http://www.example.com/customers/12345/orders</em></li>
<li><em>GET http://www.example.com/buckets/sample</em></li>
</ul>
</div>
<div class="tab-pane fade" id="put">
<p>PUT is most-often utilized for update capabilities, PUT-ing to a known resource URI with the request request body containing the newly-updated representation of the original resource.</p>
<p>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.</p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>If, for instance, calling PUT on a resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens and it may be enough to document that the call is not idempotent. However, it's recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non-idempotent requests.</p>
<p><strong>Examples:</strong></p>
<ul>
<li><em>PUT http://www.example.com/customers/12345</em></li>
<li><em>PUT http://www.example.com/customers/12345/orders/98765</em></li>
<li><em>PUT http://www.example.com/buckets/secret_stuff</em></li>
</ul>
</div>
<div class="tab-pane fade" id="post">
<p>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.</p>
<p>On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.</p>
<p>POST is neither safe or 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.</p>
<p><strong>Examples:</strong></p>
<ul>
<li><em>POST http://www.example.com/customers</em></li>
<li><em>POST http://www.example.com/customers/12345/orders</em></li>
</ul>
</div>
<div class="tab-pane fade" id="delete">
<p>DELETE is pretty easy to understand. It is used to delete a resource identified by a URI.
<p>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.</p>
<p>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.</p>
<p>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 makes DELETE operations no longer idempotent, but is an appropriate compromise if resources are removed from the database instead of being simply marked as deleted.</p>
<p><strong>Examples:</strong></p>
<ul>
<li><em>DELETE http://www.example.com/customers/12345</em></li>
<li><em>DELETE http://www.example.com/customers/12345/orders</em></li>
<li><em>DELETE http://www.example.com/bucket/sample</em></li>
</ul>
</div>
</div>
</div>
</div>
<hr>
<footer>
<p>
&copy;Pearson eCollege, 2012. All rights reserved.
</p>
</footer>
</div> <!-- /container -->
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </a>
<a class="brand" href="http://www.restapitutorial.com">REST API Tutorial</a>
<div class="nav-collapse">
<ul class="nav">
<li><a href="../index.html">Home</a></li>
<li class="dropdown active" id="api-school"><a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="whatisrest.html">What Is REST?</a></li>
<li><a href="restquicktips.html">REST Quick Tips</a></li>
<li><a href="httpmethods.html">HTTP Methods</a></li>
</ul>
</li>
<li><a href="../httpstatuscodes.html">HTTP Status Codes</a></li>
<li><a href="../resources.html">Resources</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/js/bootstrap.min.js"></script>
<a href="https://github.com/tfredrich/RestApiTutorial.com"><img style="position: absolute; top: 0; right: 0; border: 0; z-index: 1050;" src="https://a248.e.akamai.net/camo.github.com/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
</body>
</html>

94
lessons/restquicktips.html Normal file
View File

@ -0,0 +1,94 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>HTTP Methods for RESTful Services</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="RESTful API or Web Service Quick Tips. Want to learn the high points of creating a REST API? Here's the Web Services in 60-seconds version.">
<meta name="author" content="Todd Fredrich, Pearson eCollege">
<!-- Le styles -->
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap.min.css" rel="stylesheet">
<style type="text/css">
body {
padding-top: 60px;
padding-bottom: 40px;
}
</style>
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap-responsive.min.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="//html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-31328878-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="container">
<div class="row">
<div class="span12">
<h1>REST API Quick Tips</h1>
<p>Whether it's technically RESTful or not (according to the six constraints mentioned above), here are a few recommended REST-like concepts that will result in better, more usable services:</p>
<h2>Use HTTP Verbs to Mean Something</h2>
<p>Any API consumer is capable of sending GET, POST, PUT, and DELETE verbs, and they greatly enhance the clarity of what a given request does. Also, GET requests must not change any underlying resource data. Measurements and tracking may still occur, which updates data, but not resource data identified by the URI.</p>
<h2>Sensible Resource Names</h2>
<p>Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&amp;id=23) improves the clarity of what a given request does. Using URL query-string parameters is fantastic for filtering, but not for resource names.</p>
<p>Appropriate resource names provide context for a service request, increasing understandability of the service API. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications.</p>
<p>Resource names should be nouns—avoid verbs as resource names. It makes things more clear. Use the HTTP methods to specify the verb portion of the request.</p>
<h2>XML and JSON</h2>
<p>Favor JSON support, but unless the costs of offering both JSON and XML are staggering, offer them both. Ideally, let consumers switch between them by just changing an extension from .xml to .json. In addition, for supporting AJAX-style user interfaces, a wrapped response is very helpful. Provide a wrapped response, either by default or for separate extensions, such as .wjson and .wxml to indicate the client is requesting a wrapped JSON or XML response.</p>
<p>JSON in regards to a "standard" has very few requirements. And those requirements are only syntactical in nature, not about content format or layout. In other words, the JSON response to a REST service call is very much part of the contract—not described in a standard. More about the JSON data format can be found at <a href="http://www.json.org/">http://www.json.org/</a>.</p>
<p>Regarding XML use in REST services, XML standards and conventions are really not in play other than to utilize syntactically correct tags and text. In particular, namespaces are not, nor should they be use in a RESTful service context. XML that is returned is 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, see the first paragraph for this tip&mdash;the cost of XML will be staggering. In our experience nobody uses the XML responses anyway. It's just too expensive to process.</p>
<h2>Create Fine-Grained Resources</h2>
<p>When starting out, it's much easier to create APIs that mimic the underlying application domain or database architecture of your system. Eventually, you'll want aggregate services—services that utilize multiple underlying resources to reduce chattiness. But it's much easier to create larger resources later from individual resources than it is to create fine-grained or individual resources from larger aggregates. Make it easy on yourself and start with small, easily defined resources, providing CRUD functionality on those. You can create those use-case-oriented, chattiness-reducing resources later.</p>
<h2>Consider Connectedness</h2>
<p>One of the principles of REST is connectedness—via hypermedia links. While services are still useful without them, APIs become more self-descriptive when links are returned in the response. At the very least, a 'self' reference informs clients how the data was or can be retrieved. Additionally, utilize the Location header to contain a link on resource creation via POST. For collections returned in a response that support pagination, 'first', 'last', 'next' and 'prev' links at a minimum are very helpful.</p>
</div>
</div>
<hr>
<footer>
<p>
&copy;Pearson eCollege, 2012. All rights reserved.
</p>
</footer>
</div> <!-- /container -->
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </a>
<a class="brand" href="http://www.restapitutorial.com">REST API Tutorial</a>
<div class="nav-collapse">
<ul class="nav">
<li><a href="../index.html">Home</a></li>
<li class="dropdown active" id="api-school"><a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="whatisrest.html">What Is REST?</a></li>
<li><a href="restquicktips.html">REST Quick Tips</a></li>
<li><a href="httpmethods.html">HTTP Methods</a></li>
</ul>
</li>
<li><a href="../httpstatuscodes.html">HTTP Status Codes</a></li>
<li><a href="../resources.html">Resources</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/js/bootstrap.min.js"></script>
<a href="https://github.com/tfredrich/RestApiTutorial.com"><img style="position: absolute; top: 0; right: 0; border: 0; z-index: 1050;" src="https://a248.e.akamai.net/camo.github.com/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
</body>
</html>

97
lessons/whatisrest.html Normal file
View File

@ -0,0 +1,97 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>What is REST?</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A tutorial on the six primary REST constraints as explained by Roy Fielding">
<meta name="author" content="Todd Fredrich, Pearson eCollege">
<!-- Le styles -->
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap.min.css" rel="stylesheet">
<style type="text/css">
body {
padding-top: 60px;
padding-bottom: 40px;
}
</style>
<link href="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/css/bootstrap-responsive.min.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="//html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-31328878-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="container">
<div class="row">
<div class="span10">
<h1>What Is REST?</h1>
</div>
<div class="span2">
<ul class="pager">
<li>
<a href="#">Previous</a>
</li>
<li>
<a href="#">Next</a>
</li>
</ul>
</div>
<div class="span12">
<iframe width="853" height="480" src="http://www.youtube.com/embed/llpr5924N7E" frameborder="0" allowfullscreen></iframe>
</div>
</div>
<div class="row">
<div class="span12">
<p>Content here...</p>
</div>
</div>
<hr>
<footer>
<p>
&copy;Pearson eCollege, 2012. All rights reserved.
</p>
</footer>
</div> <!-- /container -->
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </a>
<a class="brand" href="http://www.restapitutorial.com">REST API Tutorial</a>
<div class="nav-collapse">
<ul class="nav">
<li><a href="../index.html">Home</a></li>
<li class="dropdown active" id="api-school"><a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="whatisrest.html">What Is REST?</a></li>
<li><a href="restquicktips.html">REST Quick Tips</a></li>
<li><a href="httpmethods.html">HTTP Methods</a></li>
</ul>
</li>
<li><a href="../httpstatuscodes.html">HTTP Status Codes</a></li>
<li><a href="../resources.html">Resources</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="https://d7im4lln3lvbg.cloudfront.net/bootstrap/2.0.1/js/bootstrap.min.js"></script>
<a href="https://github.com/tfredrich/RestApiTutorial.com"><img style="position: absolute; top: 0; right: 0; border: 0; z-index: 1050;" src="https://a248.e.akamai.net/camo.github.com/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
</body>
</html>