Restful design at work v2.0
57
RESTful Design at Work Tom Marrs Architect
-
Upload
boulder-java-users-group -
Category
Entertainment & Humor
-
view
1.433 -
download
0
description
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
Transcript of Restful design at work v2.0
RESTful Design at WorkTom MarrsArchitect
Your ProfileHow?
What?
Where?
What’s The Point?
Interface
Design
Matters
Our Agenda
RESTful Web Service
Best Practices
RESTful Web Service Design
Guidelines
RESTful API
Sources
Well-Designed RESTful
APIs
We’re Not Covering :(-
Security
Lots of Code
SOA
Design Patterns
RESTful Design Best Practices - Roadmap
Determine Data Set
Business Context
Requirements
Models
Our Case Study - Mentoring Program
A Relationship
6 meetings
Face-to-face or Phone
Mentoring Checklist
Mentoring Program - User Stories
Discover Resources
Type Example
Things Order, Member, Product
Associations Enrollment, Membership, Marriage, Employment
Processes Onboarding, Underwriting, Mentoring
Functions Driving Directions, Search
Design Resources
Uniform Interface - HTTP Methods/VerbsHTTP Verb/
Method Action
GET Read
POST Create [Update]
PUT Update [Create]
DELETE Delete
HTTP Status Codes - Typical
HTTP Verb/Method
HTTP Status Code
Meaning
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
HTTP Status Codes - Other
HTTP Verb/Method
HTTP Status Code
Meaning
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
Design URIs
Of Nouns and Verbs
Nouns - Good
Verbs - Bad
Verbs - Really Bad!/listPairs/reviewPairStatus/deletePair/updateProgress.../getAvgWaitTimeForMember - Really??/provideMemberFeedback/provideMentorFeedback
Of Nouns and Verbs ... Cont’d
Use Parameters -Simplify Associations
Before (Update Progress)/pairs/{pairId}/mentor/{mentorId}
After (Update Progress)/pairs/{pairId}?mentor={mentorId}
Pagination
API Pagination Params
Facebook ?offset=100&limit=25
Twitter ?page=5&rpp=25
LinkedIn ?start=100&count=25
Recommended /members?offset=100&limit=25
SearchingGlobal
/search?q=Fred+Smith
Scoped /search/mentors/32/feedback/q?=leader
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
Versioning ... Cont’d
Change Don’t Change
Deleted / Renamed Resources New Resources
Removed HTTP Methods New HTTP Methods
Different Data (same URI) New Data Formats
New Attributes / Data Elements
Content Negotiation
Format HTTP Request
JSON
Accept Header - application/json
simplytoast.api/members/243.json
XML
Accept Header - application/xml
simplytoast.api/members/243.xml
Error Handling
HTTP Status Codes
Error Messages?
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." } }}
JSON Object Design - JSONPad
How to Spot a Hybrid
Flickr
Flickr API Call
http://api.flickr.com/services/rest/?method=flickr.cameras.getBrandModels&brand=canon&format=json&nojsoncallback=1
Delicious
RESTful Web Service Design Guidelines
Alfresco
Apigee
Atlassian
Alfresco
Apigee
Atlassian
Well-Designed RESTful APIs
LinkedInOpen Library
Twilio
LinkedIn - People
Twilio - Send SMS
REST API Sources - ProgrammableWeb
REST API Sources - ProgrammableWeb
REST API Sources - BART API Docs
REST API Sources - BART ETA API
REST API Sources - BART-RESTClient
Other RESTful APIs
Groupon
GitHub
Roll Your Own RESTful API - Dyson
Our Agenda
RESTful Web Service
Best Practices
RESTful Web Service Design
Guidelines
RESTful API
Sources
Well-Designed RESTful
APIs
What’s The Point?
Interface
Design
Matters
Questions?Tom Marrs
Architect
http://www.linkedin.com/in/TomMarrs
Twitter: @TomMarrs
Skype: t.marrs
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
RESTful GroupsAPI Craft - http://groups.google.com/group/api-craft/topics
REST Discuss - http://tech.groups.yahoo.com/group/rest-discuss/
REST in Practice
RESTful Web Services
RESTful Web Services Cookbook
REST API Design Handbook
RESTful Java with JAX-RS
REST API Design Rulebook
