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

Improved wording on quick tips page

Browse Source
This commit is contained in:
Mark Fischer, Jr.
2015-10-03 23:22:14 -04:00
parent 816397fcd7
commit a61020bc97
1 changed files with 7 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
lessons/restquicktips.html
View File

@ -53,8 +53,8 @@
<div class="row"> <div class="row">
<div class="span12"> <div class="span12">
<p>Whether it's technically RESTful or not (according to the six constraints mentioned previously), here are a few recommended REST-like concepts. These six quick tips will result in better, more usable services.</p> <p>Whether it's technically RESTful or not (according to the six constraints mentioned previously), here are a few recommended REST-like concepts. These six quick tips will result in better, more usable services.</p>
<h2>Use HTTP Verbs to Mean Something</h2> <h2>Use HTTP Verbs to Make Your Requests Mean Something</h2>
<p>API consumers are capable of sending GET, POST, PUT, and DELETE verbs, and these verbs 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> <p>API consumers are capable of sending GET, POST, PUT, and DELETE verbs, which greatly enhance the clarity of a given request.</p>
<p>Generally, the four primary HTTP verbs are used as follows: <p>Generally, the four primary HTTP verbs are used as follows:
<dl> <dl>
<dt>GET</dt> <dt>GET</dt>
@ -66,6 +66,10 @@
<dt>POST</dt> <dt>POST</dt>
<dd>Create a new resource. Also a catch-all verb for operations that don't fit into the other categories.</dd> <dd>Create a new resource. Also a catch-all verb for operations that don't fit into the other categories.</dd>
</dl> </dl>
</p>
<h3>Note</h3>
<p>
GET requests must not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource data identified by the URI should not change.
</p> </p>
<h2>Provide Sensible Resource Names</h2> <h2>Provide Sensible Resource Names</h2>
<p>Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does.</p> <p>Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does.</p>
@ -76,7 +80,7 @@
<ul><li><strong>Good:</strong> /users/12345</li><li><strong>Poor:</strong> /api?type=user&amp;id=23</li></ul></li> <ul><li><strong>Good:</strong> /users/12345</li><li><strong>Poor:</strong> /api?type=user&amp;id=23</li></ul></li>
<li>Leverage the hierarchical nature of the URL to imply structure.</li> <li>Leverage the hierarchical nature of the URL to imply structure.</li>
<li>Design for your clients, not for your data.</li> <li>Design for your clients, not for your data.</li>
<li>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.</li> <li>Resource names should be nouns. Avoid verbs as resource names, to improve clarity. Use the HTTP methods to specify the verb portion of the request.</li>
<li>Use plurals in URL segments to keep your API URIs consistent across all HTTP methods, using the collection metaphor. <li>Use plurals in URL segments to keep your API URIs consistent across all HTTP methods, using the collection metaphor.
<ul><li><strong>Recommended:</strong> /customers/33245/orders/8769/lineitems/1</li><li><strong>Not:</strong> /customer/33245/order/8769/lineitem/1</li></ul></li> <ul><li><strong>Recommended:</strong> /customers/33245/orders/8769/lineitems/1</li><li><strong>Not:</strong> /customer/33245/order/8769/lineitem/1</li></ul></li>
<li>Avoid using collection verbiage in URLs. For example 'customer_list' as a resource. Use pluralization to indicate the collection metaphor (e.g. customers vs. customer_list).</li> <li>Avoid using collection verbiage in URLs. For example 'customer_list' as a resource. Use pluralization to indicate the collection metaphor (e.g. customers vs. customer_list).</li>