Skip to content
This repository has been archived by the owner on Mar 3, 2022. It is now read-only.

Document links integrated #57

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 16 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

# White House Web API Standards

* [Guidelines](#guidelines)
Expand All @@ -20,7 +21,7 @@ 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/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)
* [Fielding's Dissertation on REST](http://ics.uci.edu/~fielding/pubs/dissertation/top.htm)

## Pragmatic REST

Expand All @@ -47,34 +48,34 @@ These guidelines aim to support a truly RESTful API. Here are a few exceptions:

### Good URL examples
* List of magazines:
* GET http://www.example.gov/api/v1/magazines.json
* GET http://example.gov/api/v1/magazines.json
* Filtering is a query:
* 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
* GET http://example.gov/api/v1/magazines.json?year=2011&sort=desc
* GET http://example.gov/api/v1/magazines.json?topic=economy&year=2011
* A single magazine in JSON format:
* GET http://www.example.gov/api/v1/magazines/1234.json
* GET http://example.gov/api/v1/magazines/1234.json
* All articles in (or belonging to) this magazine:
* GET http://www.example.gov/api/v1/magazines/1234/articles.json
* GET http://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:
* GET http://www.example.gov/api/v1/magazines/1234.json?fields=title,subtitle,date
* GET http://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

### Bad URL examples
* Non-plural noun:
* http://www.example.gov/magazine
* http://www.example.gov/magazine/1234
* http://www.example.gov/publisher/magazine/1234
* http://example.gov/magazine
* http://example.gov/magazine/1234
* http://example.gov/publisher/magazine/1234
* Verb in URL:
* http://www.example.gov/magazine/1234/create
* http://example.gov/magazine/1234/create
* Filter outside of query string
* http://www.example.gov/magazines/2011/desc
* http://example.gov/magazines/2011/desc

## 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.
HTTP verbs, or methods, should be used in compliance with their definitions under the [HTTP/1.1](http://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 |
Expand Down Expand Up @@ -122,7 +123,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",
"moreInfo" : "http://www.example.gov/developer/path/to/help/for/444444,
"moreInfo" : "http://example.gov/developer/path/to/help/for/444444,
http://drupal.org/node/444444",
}

Expand Down Expand Up @@ -276,7 +277,7 @@ JSONP is easiest explained with an example. Here's one from [StackOverflow](http

> For example, say the server expects a parameter called "callback" to enable its JSONP capabilities. Then your request would look like:

> http://www.xyz.com/sample.aspx?callback=mycallback
> http://xyz.com/sample.aspx?callback=mycallback

> Without JSONP, this might return some basic javascript object, like so:

Expand Down