diff --git a/index.html b/index.html index 6bb38eb..8c09652 100644 --- a/index.html +++ b/index.html @@ -69,8 +69,8 @@ valueOf()+(h?'&utmxhash='+escape(h.substr(1)):'')+
-

Learn REST: A RESTful Tutorial

-

Building restful web services, like other programming skills is part art, part science. As the Internet industry progresses, creating a REST API becomes more concrete, with emerging best practices. As RESTful Web services don't follow a prescribed standard except for HTTP, it's important to build your RESTful API in accordance with industry best practices to ease development and simplify client adoption.

+

Learn REST: A RESTful Tutorial

+

Building RESTful web services, like other programming skills is part art, part science. As the Internet industry progresses, creating a REST API becomes more concrete with emerging best practices. As RESTful web services don't follow a prescribed standard except for HTTP, it's important to build your RESTful API in accordance with industry best practices to ease development and increase client adoption.

Presently, there aren't a lot of REST API guides to help the lonely developer. RestApiTutorial.com is dedicated to tracking REST API best practices and making resources available to enable quick reference and self education for the development crafts-person. We'll discuss both the art and science of creating REST Web services.

—Todd Fredrich, REST API Expert

Jump in with What Is REST?, an overview of concepts and constraints of the RESTful architecture.

diff --git a/lessons/restquicktips.html b/lessons/restquicktips.html index df2fd2f..9a145a6 100644 --- a/lessons/restquicktips.html +++ b/lessons/restquicktips.html @@ -67,8 +67,8 @@

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.

-

Use HTTP Verbs to Mean Something

-

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.

+

Use HTTP Verbs to Make Your Requests Mean Something

+

API consumers are capable of sending GET, POST, PUT, and DELETE verbs, which greatly enhance the clarity of a given request.

Generally, the four primary HTTP verbs are used as follows:

GET
@@ -80,6 +80,10 @@
POST
Create a new resource. Also a catch-all verb for operations that don't fit into the other categories.
+

+

Note

+

+ 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.

Provide Sensible Resource Names

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.

@@ -90,7 +94,7 @@
  • Good: /users/12345
  • Poor: /api?type=user&id=23
  • Leverage the hierarchical nature of the URL to imply structure.
  • Design for your clients, not for your data.
    • -
  • 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.
    • +
  • 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.
  • Use plurals in URL segments to keep your API URIs consistent across all HTTP methods, using the collection metaphor.
    • Recommended: /customers/33245/orders/8769/lineitems/1
    • Not: /customer/33245/order/8769/lineitem/1
  • 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).