From 80a08f8a2c9dc48f2f0943527037d757e22ebc87 Mon Sep 17 00:00:00 2001 From: Carlos Eberhardt Date: Sat, 23 Mar 2013 19:42:00 -0500 Subject: [PATCH 01/16] Correct capitalization on Apigee and links for resources. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8446ac6..a019c16 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ This document provides guidelines and examples for White House Web APIs, encoura This document borrows heavily from: * [Designing HTTP Interfaces and RESTful Web Services](http://munich2012.drupal.org/program/sessions/designing-http-interfaces-and-restful-web-services) -* API Facade Pattern, by Brian Mulloy, APIGee -* Web API Design, by Brian Mulloy, APIGee +* [API Facade Pattern](http://apigee.com/about/content/api-fa%C3%A7ade-pattern), by Brian Mulloy, Apigee +* [Web API Design](http://pages.apigee.com/web-api-design-ebook.html), by Brian Mulloy, Apigee * [Fieldings Dissertation on REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) ## Pragmatic REST From e1a5e6202dec5d7710a0f06d1ad30ec4380b5434 Mon Sep 17 00:00:00 2001 From: Mal Curtis Date: Mon, 25 Mar 2013 11:39:15 +1300 Subject: [PATCH 02/16] Fix spelling mistake --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8446ac6..a6313cb 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ Use three simple, common response codes indicating (1) success, (2) failure due * offset=50 means, ‘begin with record number fifty’ * limit=25 means, ‘return 25 records’ -Information about record limits should also be included in the Example resonse. Example: +Information about record limits should also be included in the Example response. Example: { "metadata": { From b6bf945194d56ac9980e33a7accf2189c12f38f7 Mon Sep 17 00:00:00 2001 From: Philip Ashlock Date: Thu, 2 May 2013 12:54:40 -0300 Subject: [PATCH 03/16] Specifying HTTP verb (GET) on other Good URL examples for consistency Some of the URLS listed included the verb (eg GET and POST), but not all. Just wanted to be consistent. --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c1f7e75..58fb80a 100644 --- a/README.md +++ b/README.md @@ -47,18 +47,18 @@ These guidelines aim to support a truly RESTful API. Here are a few exceptions: ### Good URL examples * List of magazines: - * http://www.example.gov/api/v1/magazines.json + * GET http://www.example.gov/api/v1/magazines.json * Filtering is a query: - * http://www.example.gov/api/v1/magazines.json?year=2011&sort=desc - * http://www.example.gov/api/v1/magazines.json?topic=economy&year=2011 + * GET http://www.example.gov/api/v1/magazines.json?year=2011&sort=desc + * GET http://www.example.gov/api/v1/magazines.json?topic=economy&year=2011 * A single magazine in JSON format: - * http://www.example.gov/api/v1/magazines/1234.json + * GET http://www.example.gov/api/v1/magazines/1234.json * All articles in (or belonging to) this magazine: - * http://www.example.gov/api/v1/magazines/1234/articles.json + * GET http://www.example.gov/api/v1/magazines/1234/articles.json * All articles in this magazine in XML format: * GET http://example.gov/api/v1/magazines/1234/articles.xml * Specify optional fields in a comma separated list: - * http://www.example.gov/api/v1/magazines/1234.json?fields=title,subtitle,date + * GET http://www.example.gov/api/v1/magazines/1234.json?fields=title,subtitle,date * Add a new article to a particular magazine: * POST http://example.gov/api/v1/magazines/1234/articles From 0911878560dd0714cf1245b05a3790103bfe496f Mon Sep 17 00:00:00 2001 From: Noah Kunin Date: Fri, 3 May 2013 12:32:15 -0300 Subject: [PATCH 04/16] Better contextualize the HTTP Verbs table As an example, as opposed to a declarative part of the standard. Also gives context to HTTP/1.1 method definitions. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index c1f7e75..089491c 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,9 @@ These guidelines aim to support a truly RESTful API. Here are a few exceptions: ## HTTP Verbs +HTTP verbs, or methods, should be used in compliance with their definitions under the [HTTP/1.1](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) standard. +The action taken on the representation will be contextual to the media type being worked on and its current state. Here's an example of how HTTP verbs map to create, read, update, delete operations in a particular context: + | HTTP METHOD | POST | GET | PUT | DELETE | | ----------- | --------------- | --------- | ----------- | ------ | | CRUD OP | CREATE | READ | UPDATE | DELETE | From 55d441b43285af2f1e3f97d890456ae7da216d13 Mon Sep 17 00:00:00 2001 From: Garrison Locke Date: Mon, 17 Jun 2013 16:01:16 -0300 Subject: [PATCH 05/16] Update README.md Fixed typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c1f7e75..08a3440 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ Use three simple, common response codes indicating (1) success, (2) failure due * offset=50 means, ‘begin with record number fifty’ * limit=25 means, ‘return 25 records’ -Information about record limits should also be included in the Example resonse. Example: +Information about record limits should also be included in the Example response. Example: { "metadata": { From f28b1d79ad14237113ff2b4551778a7cdd8e919a Mon Sep 17 00:00:00 2001 From: TravisCarden Date: Wed, 28 Aug 2013 15:19:16 -0500 Subject: [PATCH 06/16] Fixed typo in JSON. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c1f7e75..7db84b8 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Error responses should include a common HTTP status code, message for the develo suggestions about how to solve their problems here", "userMessage" : "This is a message that can be passed along to end-users, if needed.", "errorCode" : "444444", - "more info" : "http://www.example.gov/developer/path/to/help/for/444444, + "moreInfo" : "http://www.example.gov/developer/path/to/help/for/444444, http://drupal.org/node/444444", } From 6c93d072570ace469f86303c4a9fd31b9e8f0527 Mon Sep 17 00:00:00 2001 From: Bryan Hirsch Date: Thu, 29 Aug 2013 06:43:03 -0400 Subject: [PATCH 07/16] Clarified error code description. Status codes should be integers. modified: README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7db84b8..a3694ac 100644 --- a/README.md +++ b/README.md @@ -111,10 +111,10 @@ Values in keys: ## Error handling -Error responses should include a common HTTP status code, message for the developer, message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined error number), links where developers can find more info. For example: +Error responses should include a common HTTP status code, message for the developer, message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined ID), links where developers can find more info. For example: { - "status" : "400", + "status" : 400, "developerMessage" : "Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here", "userMessage" : "This is a message that can be passed along to end-users, if needed.", From c3fce28a99b31113e7efe7690217960fd25732be Mon Sep 17 00:00:00 2001 From: Ian Ward Date: Thu, 24 Oct 2013 14:11:38 -0400 Subject: [PATCH 08/16] fix offset meaning in record limits example --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a3694ac..d3eecd4 100644 --- a/README.md +++ b/README.md @@ -141,9 +141,9 @@ Use three simple, common response codes indicating (1) success, (2) failure due ## Record limits * If no limit is specified, return results with a default limit. -* To get records 50 through 75 do this: +* To get records 51 through 75 do this: * http://example.gov/magazines?limit=25&offset=50 - * offset=50 means, ‘begin with record number fifty’ + * offset=50 means, ‘skip the first 50 records’ * limit=25 means, ‘return 25 records’ Information about record limits should also be included in the Example resonse. Example: From 780855d946d24636a9502c2185344340bfd76306 Mon Sep 17 00:00:00 2001 From: James Abley Date: Fri, 22 Mar 2013 09:18:50 +0000 Subject: [PATCH 09/16] Minor grammar change It is the dissertation of Roy Fielding --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a3694ac..d86c9ec 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ This document borrows heavily from: * [Designing HTTP Interfaces and RESTful Web Services](http://munich2012.drupal.org/program/sessions/designing-http-interfaces-and-restful-web-services) * API Facade Pattern, by Brian Mulloy, Apigee * Web API Design, by Brian Mulloy, Apigee -* [Fieldings Dissertation on REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) +* [Fielding's Dissertation on REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) ## Pragmatic REST From 13627baa1a14db4fb68334cbb51a04116b467527 Mon Sep 17 00:00:00 2001 From: jrep Date: Thu, 31 Oct 2013 12:59:25 -0500 Subject: [PATCH 10/16] Clarify count field in responses --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index df999a4..c70a208 100644 --- a/README.md +++ b/README.md @@ -147,21 +147,19 @@ Use three simple, common response codes indicating (1) success, (2) failure due * To get records 51 through 75 do this: * http://example.gov/magazines?limit=25&offset=50 * offset=50 means, ‘skip the first 50 records’ - * limit=25 means, ‘return 25 records’ + * limit=25 means, ‘return a maximum of 25 records’ -Information about record limits should also be included in the Example response. Example: +Information about record limits and total available count should also be included in the response. Example: { "metadata": { "resultset": { - "count": 50, + "count": 227, "offset": 25, "limit": 25 } }, - "results": [ - { .. } - ] + "results": [] } ## Request & Response Examples From 480c77b3138a291faae97f6ef94eb6e092f14772 Mon Sep 17 00:00:00 2001 From: jrep Date: Fri, 1 Nov 2013 15:17:28 -0500 Subject: [PATCH 11/16] Distinguished example request and response bodies and changed POST example to allow for multiple items per pull request #29 from jrep/FULL_POST. --- README.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c70a208..885e5b6 100644 --- a/README.md +++ b/README.md @@ -174,6 +174,8 @@ Information about record limits and total available count should also be include Example: http://example.gov/api/v1/magazines.json +Response body: + { "metadata": { "resultset": { @@ -219,6 +221,8 @@ Example: http://example.gov/api/v1/magazines.json Example: http://example.gov/api/v1/magazines/[id].json +Response body: + { "id": "1234", "type": "magazine", @@ -236,17 +240,20 @@ Example: http://example.gov/api/v1/magazines/[id].json Example: Create – POST http://example.gov/api/v1/magazines/[id]/articles - { - "title": "Raising Revenue", - "author_first_name": "Jane", - "author_last_name": "Smith", - "author_email": "jane.smith@example.gov", - "year": "2012" - "month": "August" - "day": "18" - "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam eget ante ut augue scelerisque ornare. Aliquam tempus rhoncus quam vel luctus. Sed scelerisque fermentum fringilla. Suspendisse tincidunt nisl a metus feugiat vitae vestibulum enim vulputate. Quisque vehicula dictum elit, vitae cursus libero auctor sed. Vestibulum fermentum elementum nunc. Proin aliquam erat in turpis vehicula sit amet tristique lorem blandit. Nam augue est, bibendum et ultrices non, interdum in est. Quisque gravida orci lobortis... " - - } +Request body: + + [ + { + "title": "Raising Revenue", + "author_first_name": "Jane", + "author_last_name": "Smith", + "author_email": "jane.smith@example.gov", + "year": "2012", + "month": "August", + "day": "18", + "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam eget ante ut augue scelerisque ornare. Aliquam tempus rhoncus quam vel luctus. Sed scelerisque fermentum fringilla. Suspendisse tincidunt nisl a metus feugiat vitae vestibulum enim vulputate. Quisque vehicula dictum elit, vitae cursus libero auctor sed. Vestibulum fermentum elementum nunc. Proin aliquam erat in turpis vehicula sit amet tristique lorem blandit. Nam augue est, bibendum et ultrices non, interdum in est. Quisque gravida orci lobortis... " + } + ] ## Mock Responses From 6306e9388fd8feb9b6cc07b4c35d88ee72b5906b Mon Sep 17 00:00:00 2001 From: TravisCarden Date: Tue, 5 Nov 2013 11:19:16 -0600 Subject: [PATCH 12/16] Fixed broken link in table of contents. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 885e5b6..5e061fe 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ * [Error handling](#error-handling) * [Versions](#versions) * [Record limits](#record-limits) -* [Request & Response Examples](#request-response-examples) +* [Request & Response Examples](#request--response-examples) * [Mock Responses](#mock-responses) * [JSONP](#jsonp) From c18e7c54b7aef11177a29beb0931ddfa2ef4a59e Mon Sep 17 00:00:00 2001 From: TravisCarden Date: Tue, 5 Nov 2013 12:07:51 -0600 Subject: [PATCH 13/16] Fixed a minor typo. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e061fe..c9dc0f2 100644 --- a/README.md +++ b/README.md @@ -266,7 +266,7 @@ Note: If the mock parameter is included in a request to the production environme ## JSONP -JSONP is easiest explained with an example. Here's a one from [StackOverflow](http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about?answertab=votes#tab-top): +JSONP is easiest explained with an example. Here's one from [StackOverflow](http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about?answertab=votes#tab-top): > Say you're on domain abc.com, and you want to make a request to domain xyz.com. To do so, you need to cross domain boundaries, a no-no in most of browserland. From 237473ae5a4fd382224349c419f6f664d830f728 Mon Sep 17 00:00:00 2001 From: Pascal Borreli Date: Wed, 6 Nov 2013 18:02:29 +0000 Subject: [PATCH 14/16] Fixed typo --- drupal/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drupal/README.md b/drupal/README.md index 348cbca..4dcace7 100644 --- a/drupal/README.md +++ b/drupal/README.md @@ -16,7 +16,7 @@ Note that when you define new CRUD operations, services will automatically expos Be sure that your endpoint path conforms to the Whitehouse API Standards: [endpoint_path] = /api/[version]/ -These default URL patterns neccesitate a default, corresponding argument structure. For example: +These default URL patterns necessitate a default, corresponding argument structure. For example: * CREATE operations expect argument ‘source’ to be defined as ‘data’ * UPDATE operations expect at least two arguments, one with 'source' defined as 'path', and one with 'source' defined as 'data' * Etc. From 832a7de57a059bc2ae9266c68c6923df380232bf Mon Sep 17 00:00:00 2001 From: Andre Dickson Date: Mon, 31 Mar 2014 20:13:25 -0300 Subject: [PATCH 15/16] Updated broken video link Video at link for Designing HTTP Interfaces and RESTful Web Services was removed from bliptv. Exchanged with youtube link for the talk. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c9dc0f2..c299091 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX). This document borrows heavily from: -* [Designing HTTP Interfaces and RESTful Web Services](http://munich2012.drupal.org/program/sessions/designing-http-interfaces-and-restful-web-services) +* [Designing HTTP Interfaces and RESTful Web Services](https://www.youtube.com/watch?v=zEyg0TnieLg) * [API Facade Pattern](http://apigee.com/about/content/api-fa%C3%A7ade-pattern), by Brian Mulloy, Apigee * [Web API Design](http://pages.apigee.com/web-api-design-ebook.html), by Brian Mulloy, Apigee * [Fielding's Dissertation on REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) From b0aff34a527cf7f15d87a9826b96c856f60bf8e0 Mon Sep 17 00:00:00 2001 From: TravisCarden Date: Mon, 23 Feb 2015 23:28:53 -0600 Subject: [PATCH 16/16] Fixed #41 - broken link to API Facade Pattern ebook. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c299091..38a1b0d 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ This document provides guidelines and examples for White House Web APIs, encoura This document borrows heavily from: * [Designing HTTP Interfaces and RESTful Web Services](https://www.youtube.com/watch?v=zEyg0TnieLg) -* [API Facade Pattern](http://apigee.com/about/content/api-fa%C3%A7ade-pattern), by Brian Mulloy, Apigee +* [API Facade Pattern](http://apigee.com/about/resources/ebooks/api-fa%C3%A7ade-pattern), by Brian Mulloy, Apigee * [Web API Design](http://pages.apigee.com/web-api-design-ebook.html), by Brian Mulloy, Apigee * [Fielding's Dissertation on REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)