API design principles for accelerated development
Download as PPTX, PDF4 likes3,883 views
Audio from this presentation is available at https://archive.org/details/api_design One of the largest issues in API architecture development is that the task is often driven by the pragmatic indoctrination of a specification into a product rather than designing around the speed and ease of development, usually due to a separation between the engineering teams and their core developer user base. Extending upon the ideas of API design around developer accelerated development, we will take a deeper look into some of the great techniques delivered to us through the RESTful specification, applying them to developer API consumption practices with the intention of creating efficient best practices for rapid development. Within this talk we will explore what we have learned through reconstructing our API backbone at PayPal for our developer community, including: - API automation practices for code reduction and application longevity - Open security standards that promote developer integration ease and maintain strict security practices - RESTful API architecture best practices for developer centric accelerated development
!["links": [
{
"href":"https://api.sandbox.paypal.com/v1/payments/
authorization/6H149011U8307001M",
"rel":"self",
"method":"GET"
},{
"href":"https://api.sandbox.paypal.com/v1/payments/
authorization/6H149011U8307001M/capture",
"rel":"capture",
"method":"POST"
},{
"href":"https://api.sandbox.paypal.com/v1/payments/
authorization/6H149011U8307001M/void",
"rel":"void",
"method":"POST"
}
]](https://image.slidesharecdn.com/2013octsvcodecampapidesignaccelerateddevelopment-131004130412-phpapp02/85/API-design-principles-for-accelerated-development-26-320.jpg)
![Representations on Update / Create
{ "id": "PAY-17S8410768582940NKEE66EQ",
"create_time": "2013-01-31T04:12:02Z",
"update_time": "2013-01-31T04:12:04Z",
"state": "approved",
"intent": "sale",
"payer": {...},
"transactions": [{...}],
"links": [{...}] }
Send enough detail to not have to make another
request to the API](https://image.slidesharecdn.com/2013octsvcodecampapidesignaccelerateddevelopment-131004130412-phpapp02/85/API-design-principles-for-accelerated-development-39-320.jpg)
Ad
More Related Content
What's hot (20)
Viewers also liked (9)
Ad
Similar to API design principles for accelerated development (20)
Ad
More from Jonathan LeBlanc (20)
Recently uploaded (20)
API design principles for accelerated development
- 1. API Design Principles For Accelerated Development Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism PayPal North America
- 2. The Exploration of API Design Blank Slate Constraints
- 3. Building APIs for Developers
- 5. Developer efficiency task 1 Lowering perceived latency for developers Lower Perceived Latency
- 6. What’s the Tradeoff? System Layering Result Caching
- 7. Layering the System Encapsulates legacy systems Simplified components Better load balancing abilities Systems can evolve independently
- 9. Stateless System Latency Issues Data Duplication A + B A + C
- 10. Caching for Latency Reduction
- 11. Developer efficiency task 2 Use HTTP properly – standard request and response types Not Hindering with HTTP
- 13. Requests and Responses GET / PUT / POST / DELETE have specific actions Proper status codes and error responses
- 14. Don’t do This {"error": "error 10008"} Do This HTTP/1.1 400 Bad Request Content-Length: 35 {"message":"Problems parsing JSON"} Descriptive Messaging
- 15. X-Rate-Limit-Limit Number of requests allowed in current period X-Rate-Limit-Remaining Number of remaining requests in current period X-Rate-Limit-Reset Number of seconds left in current period Useful Responses on Rate Limiting
- 16. Use Status Cats! http://httpcats.herokuapp.com/ Don’t Want to Use Boring Responses?
- 17. Allowing HTTP Overriding curl -i -X POST https://api.sandbox.paypal.com/v1/payments/ -H "Content-Type:application/json" -H "X-HTTP-Method-Override: PUT" Injecting PUT / DELETE methods when HTTP client only supports GET / POST
- 19. What’s the Tradeoff? Payload Size Code Length
- 20. RESTful API Core Concepts Honor HTTP request verbs Use proper HTTP status codes No version numbering in URIs Return format via HTTP Accept header Double Rainbow: Discovery via HATEOAS
- 21. To Version or Not to Version
- 22. Uniform Interface Sub-Constraints Resource Identification Resources must be manipulated via representations Self descriptive messages Hypermedia as the engine of application state
- 23. How we Normally Consume APIs
- 24. Using HATEOAS to Automate
- 25. How HATEOAS Works curl -v -X GET https://api.sandbox.paypal.com/v1/payments/authoriz ation/2DC87612EK520411B -H "Content-Type:application/json" -H "Authorization:Bearer ENxom5Fof1KqAffEsXtx1HTEK__KVdIsaCYF8C" You make an API request
- 27. Developer efficiency task 2 Secure Data Resources
- 28. What’s the Tradeoff? Security Usability
- 29. Some Security Models Proprietary Solution Basic Authentication OAuth 1.0a OAuth 2 / OpenID Connect Cross-Origin Resource Sharing (CORS)
- 30. A Modern Approach CORS Client-side SDK OpenID Connect Server-side SDKs
- 31. Working on the Server Side SDKs Secure Token Management Simplified Development
- 32. Cross Origin Issues and Options Access to other domains / subdomains is restricted (same origin policy) JSONP to request resources across domains Only supports HTTP GET requests Cross-origin resource sharing (CORS) Supports additional range of HTTP requests
- 33. Can you use it? http://caniuse.com/cors
- 34. How Does it Work? OPTIONS /v1/oauth2/token HTTP/1.1 Origin: http://jcleblanc.com Access-Control-Request-Method: PUT Host: api.sandbox.paypal.com Accept-Language: en-US Connection: keep-alive ... Site sends Origin header to server
- 35. How Does it Work? Server responds with matching Access-Control-Allow-Origin header Access-Control-Allow-Origin: http://jcleblanc.com Access-Control-Allow-Methods: GET, POST, PUT Content-Type: text/html; charset=utf-8
- 36. Developer efficiency task 4 Offload complexity to the implementing provider Offload Complexity
- 37. The Complexities Authentication / Authorization Legacy API support Working between versioning API changes that break implementations Reduction in latency
- 38. GET /payment POST /sale POST /payment DELETE /refund GET /getSinglePayment POST /setNewSingleSale POST /addNewSinglePayment DELETE /issueSingleRefund URL Structure, Verbs, and Nouns
- 39. Representations on Update / Create { "id": "PAY-17S8410768582940NKEE66EQ", "create_time": "2013-01-31T04:12:02Z", "update_time": "2013-01-31T04:12:04Z", "state": "approved", "intent": "sale", "payer": {...}, "transactions": [{...}], "links": [{...}] } Send enough detail to not have to make another request to the API
- 40. API architecture is all about tradeoffs You are not making a perfect system, you are making a perfect system for your developers Bringing it all Together
- 41. Thanks! Questions? http://slideshare.net/jcleblanc Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism PayPal North America
Editor's Notes
- #4: At the end of the day, we need to be designing for the developers
- #5: API system standards vs. efficient developmentREST is all about the tradeoffs
- #6: Lowering perceived latency for developers
- #7: Reduction in system layeringCaching can reduce reliability (stale data)
- #8: Protects new systems from legacy APIs
- #9: Layering the system to separate legacy systems
- #12: Use HTTP properly – standard request and response types
- #16: http://stackoverflow.com/questions/16022624/examples-of-http-api-rate-limiting-http-response-headers
- #18: curl -i -H "Accept: application/json" -H "X-HTTP-Method-Override: DELETE" -X POST http://192.168.0.3:8090/persons/person/1
- #20: Heavier payloads being sent throughReduction in developer code size & scalable architecture
- #22: A lot of debate on whether versioning should go in the headers or URLhttp://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#versioninghttp://stackoverflow.com/questions/389169/best-practices-for-api-versioning
- #28: Use HTTP properly – standard request and response types
- #33: JSONP can cause XSS issues where the external site is compromised, CORS allows websites to manually parse responses to ensure security
- #37: Offload complexity to the implementing provider
- #39: Nouns are good, verbs are badhttps://blog.apigee.com/detail/restful_api_design_nouns_are_good_verbs_are_bad