Downloaded 57 times
Uploaded byMizan Riqzia
Restful api design
This document discusses best practices for designing RESTful web APIs. It covers topics such as using HTTP verbs for actions, providing sensible resource names, using response codes to indicate status, offering both JSON and XML formats, creating fine-grained resources, considering connectivity between resources, handling errors properly, using versioning, supporting pagination and partial responses, including timestamps in requests and responses, and authenticating via methods such as OAuth2. The document provides examples from existing APIs at companies like Facebook, Twilio, and LinkedIn.
More Related Content
Restful api design
- 1. by Mizan Rizqia Designinga RESTful Web API
- 2. OUTLINE ● Introduction ● Quick Tips ● Error Handling ● Versioning ● Paginate& Partial Respone ● Timestamps ● Authentication
- 3. Introduction REST Representational State Transfer Softwarearchitecture style consisting of guidelines and best practice for creating scalable web service
- 4. REST Architectural Constrains ●Client Server ● Stateless ● Cacheable ● Layered System ● Code on Demand (optional) ● Uniform Interface RESTful
- 5. 6 Quick Tips 1.UseHTTP Verbs to Mean Something ● GET ● POST ● PUT ● DELETE
- 6. 6 Quick Tips 2.ProvideSensible 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
- 7.
- 8. 6 Quick Tips 3.UseHTTP Response Codes to Indicate Status Top 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
- 9. 6 Quick Tips 4.OfferBoth JSON and XML ● Make the XML that is returned more JSON-like ● JSON-Schema (schema-style validation capabilities)
- 10. 6 Quick Tips 5.CreateFine-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
- 11. Handling Errors Why isgood 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
- 12. Handling Errors Example ●Facebook HTTP Status Code: 200 {"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"}
- 13. Handling Errors Example ●Twillio HTTP Status Code: 401 {"status" : "401", "message":"Authenticate","code": 20003, "moreinfo": "http://www.twilio.com/docs/errors/20003"}
- 14. Handling Errors Example ●SimpleGeo HTTP Status Code: 401 {"code" : 401, "message": "Authentication Required"}
- 15. Handling Errors Use HTTPStatus Code Google 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
- 16. Handling Errors How manystatus 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
- 17. Versioning “Never Release anAPI without a version and make the version mandatory”
- 18. Versioning Example ● Twilio /20140401/Accounts/ ●Salesforce /services/data/v20.0/sobjects/Accounts ● Facebook ?v=1.0
- 19. Versioning Recommendation ● Specifythe 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
- 20. Pagination & PartialRespone “Just give the information they need”
- 21. Pagination & PartialRespone ● LinkedIn /people:(id,firstname,lastname,industry) ● Facebook /joe.smith/friends?fields=id,name,picture ● Google ?fields=title,media:group(media:thumbnail)
- 22. Pagination & PartialRespone ● 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
- 23. Search ● Global Search /search?q=mizan+keren ●Scoped Search /orders/1001?q=tlab+amazing ● Formatted Search /search.xml?q=mizan+keren
- 24. Timestamp ● Don't useUnix 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
- 25. Authentication Three common waysto 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
- 26.
- 27. Complement with anSDK ● 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
- 28. 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/
- 29. Matur Sembah Nuwun Thankyou Mizan Rizqia baobaz@tlab.co.id +62-81806406692 @mizanrizqia /mizanr