Slides for Tom Marrs BJUG talk on 2/12/2013. See http://boulderjug.org/2013/01/tuesday-february-12-2013-a-night-with-tom-marrs-covering-json-and-rest.html
12. Uniform Interface -
HTTP Methods/Verbs
HTTP Verb/
Action
Method
GET Read
POST Create [Update]
PUT Update [Create]
DELETE Delete
13. HTTP Status Codes -
Typical
HTTP Verb/ HTTP Status
Meaning
Method Code
GET 200 OK
GET 404 Not Found
POST 201 Created
PUT 200 OK
PUT 404 Not Found
PUT 409 Conflict
DELETE 200 OK
DELETE 404 Not Found
DELETE 409 Conflict
14. HTTP Status Codes -
Other
HTTP
HTTP Verb/
Status Meaning
Method
Code
POST / PUT / DELETE 202 Accepted - Process request later
POST / PUT / DELETE 204 No Content
GET / PUT / DELETE 301 Moved Permanently
ALL 400 Bad Request
ALL 401 Unauthorized
ALL 500 Internal Server Error
19. Use Parameters -
Simplify Associations
Before (Update Progress)
/pairs/{pairId}/mentor/{mentorId}
After (Update Progress)
/pairs/{pairId}?mentor={mentorId}
22. Versioning
API Sample URI
Twilio /2012-07-11/Accounts/{AccountSid}
SalesForce.com /services/data/v20.0/sobjects/
Account
Facebook ?v=1.0
Recommended /v2/members
23. Versioning ... Cont’d
Change Don’t Change
Deleted / Renamed Resources New Resources
New HTTP Methods
Removed HTTP Methods
Different Data (same URI) New Data Formats
New Attributes / Data Elements
24. Content Negotiation
Format HTTP Request
Accept Header - application/json
JSON
simplytoast.api/members/243.json
Accept Header - application/xml
XML
simplytoast.api/members/243.xml
26. Error Messages?
Why or Why Not?
{
"status" : {
"user" : {
"message" : "Member Fred Smith already exists."
},
"dev" : {
"code" : 409,
"message" : "Member exists. Only a DELETE or UPDATE is
possible at this point."
}
}
}
50. RESTful API
Resources
Teach a Dog to REST - http://blog.apigee.com/detail/restful_api_design/
Apigee API Best Practices - http://blog.apigee.com/taglist/restful
rapi_doc - http://blogs.burnsidedigital.com/2011/12/generating-api-
documentation-with-rapi_doc/
RESTdoclet - https://github.com/IG-Group/RESTdoclet
API Evangelist - http://apievangelist.com/
The Programmable Web (API Directory) - http://
www.programmableweb.com/apis
Stormpath - http://www.stormpath.com/blog/designing-rest-json-apis
51. RESTful Groups
API Craft - http://groups.google.com/group/api-craft/topics
REST Discuss - http://tech.groups.yahoo.com/group/rest-discuss/
