109 lines
7.8 KiB
HTML
109 lines
7.8 KiB
HTML
<!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="span8">
|
|
<h1>REST API Quick Tips</h1>
|
|
</div>
|
|
<div class="span4">
|
|
<ul class="pager">
|
|
<li>
|
|
<a href="whatisrest.html"><i class="icon-step-backward"></i> Previous</a>
|
|
</li>
|
|
<li>
|
|
<a href="httpmethods.html">Next <i class="icon-step-forward"></i></a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="row">
|
|
<div class="span12">
|
|
<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&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—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>
|
|
©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 class="active"><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>
|