restful api design
TRANSCRIPT
by Mizan Rizqia
Designing a RESTful Web API
OUTLINE
● Introduction
● Quick Tips
● Error Handling
● Versioning
● Paginate & Partial Respone
● Timestamps
● Authentication
Introduction
RESTRepresentational State Transfer
Software architecture style consisting of guidelines and best practice for creating scalable web service
REST Architectural Constrains
● Client Server● Stateless● Cacheable● Layered System● Code on Demand
(optional)● Uniform Interface
RESTful
6 Quick Tips
1.Use HTTP Verbs to Mean Something● GET● POST● PUT● DELETE
6 Quick Tips
2.Provide Sensible Resource Name● Use identifier (clean URL)
● Good : /user/12345
● Poor : /api?type=user&id=23
● Design for your client, not for your data● Resource name = NOUNS (avoid verb)● Use PLURAL● Use lower-case● Keep URLs as SHORT as possible
Recommended : /customers/33245/orders/8769/lineitems/1
6 Quick Tips
6 Quick Tips
3.Use HTTP Response Codes to Indicate StatusTop 10 HTTP Status Code
● 403 FORBIDDEN
● 404 NOT FOUND
● 405 METHOD NOT ALLOW
● 409 CONFLICT
● 500 INTERNAL SERVER ERROR
● 200 OK
● 201 CREATED
● 204 NO CONTENT
● 400 BAD REQUEST
● 401 UNAUTORIZED
6 Quick Tips
4.Offer Both JSON and XML● Make the XML that is returned more JSON-like● JSON-Schema (schema-style validation
capabilities)
6 Quick Tips
5.Create Fine-Gained Resources● Small resources● Easy defined resources● Provide CRUD functionality● Use-case-oriented
6.Consider Connectedness● RFC5988 : The HTTP Web Linking Spesification● RFC3987 : International Resource Identifiers (IRIs)● RFC4287 : Atom-Style links
Handling Errors
Why is good error design especially important for API designer?
1. Developer learn to write code through error
2. Developer depend on well-designed error when they are throubleshooting and resolving issues
Handling Errors Example
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"}
Handling Errors Example
● Twillio
HTTP Status Code: 401
{"status" : "401", "message":"Authenticate","code": 20003, "moreinfo": "http://www.twilio.com/docs/errors/20003"}
Handling Errors Example
● SimpleGeo
HTTP Status Code: 401
{"code" : 401, "message": "Authentication Required"}
Handling Errors
Use HTTP Status Code
200 201 304 400 401 403 404 409 410 500
Netflix
200 201 304 400 401 403 404 412 500
Digg
200 400 401 403 404 410 500 503
Handling Errors
How many status codes should you use for your API? (minimum)1.Success – Everything worked
2.Client error – The application did something wrong
3.Server error – The API did something wrong
● 200 OK
● 400 Bad Request
● 500 Internal Server Error
More info: HTTP Status Codes
Versioning
“Never Release an API without a version and make the version mandatory”
Versioning Example
● Twilio/20140401/Accounts/
● Salesforce/services/data/v20.0/sobjects/Accounts
● Facebook?v=1.0
Versioning Recommendation
● Specify the version with a 'v' prefix, don't use the dot notation.
– /v1/dogs
– /v2/customers
● How many version should you maintain?
– At least one version back● Should version and format be in URL or headers?
– If it logic, put in URL
– If it doesn't change logic (like Oauth), put it in the header
Pagination & Partial Respone
“Just give the information they need”
Pagination & Partial Respone
● LinkedIn/people:(id,firstname,lastname,industry)
● Facebook/joe.smith/friends?fields=id,name,picture
● Google?fields=title,media:group(media:thumbnail)
Pagination & Partial Respone
● Recommendation– Add optional fields in comma-delimited list
/dogs?field=name,color,location
/tickets?sort=updated_at
/tickets?sort=priority,created_at
– Use limit & offset to paginate object/dogs?limit=25&offset=50
Search
● Global Search/search?q=mizan+keren
● Scoped Search/orders/1001?q=tlab+amazing
● Formatted Search/search.xml?q=mizan+keren
Timestamp
● Don't use Unix Timestamps– 1427736345 (ISO 8601:2015-03-30T17:25:45Z)
● Use standard Timestamps– ISO-8601
– 2015-03-30T16:31:53+00:00
– 2015-03-30T16:31:53Z
Authentication
Three common ways to go with authentication
1. If your API has user-based authentication
Oauth2 - demo
2. If you just need to password protect
HTTP Basic Authentication (not secure)
3. if you want to provide an API key or other sorts of single-string authentication
Oauth + HTTP Basic Authentication
Authentication – OAuth2 Flow
Complement with an SDK
● Speed adoption on a specific platform
● Simplify integration effort required to work with your API
● An SDK can help reduce bad or inefficient code
● As a developer resource
– Yahoo
– Paypal● To market your API specific community
Reference
● https://pages.apigee.com/web-api-design-ebook.html
● http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
● http://www.restapitutorial.com/
● http://bshaffer.github.io/oauth2-server-php-docs/
● http://code.tutsplus.com/tutorials/laravel-4-a-start-at-a-restful-api-updated--net-29785
● http://www.sitepoint.com/build-rest-resources-laravel/
