From 816397fcd728c0b815985cdefb6e29df1e68f401 Mon Sep 17 00:00:00 2001 From: "Mark Fischer, Jr." Date: Sat, 3 Oct 2015 23:12:32 -0400 Subject: [PATCH 1/2] Fixed grammar and spelling on index page --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 70ce4b2..261d0bd 100644 --- a/index.html +++ b/index.html @@ -61,8 +61,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.

From a61020bc97d92dca1a4c4fb35740c0f773ad8aa3 Mon Sep 17 00:00:00 2001 From: "Mark Fischer, Jr." Date: Sat, 3 Oct 2015 23:22:14 -0400 Subject: [PATCH 2/2] Improved wording on quick tips page --- lessons/restquicktips.html | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/lessons/restquicktips.html b/lessons/restquicktips.html index 1ed2c6d..17624a6 100644 --- a/lessons/restquicktips.html +++ b/lessons/restquicktips.html @@ -53,8 +53,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
@@ -66,6 +66,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.

@@ -76,7 +80,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).