1 / 41

API design principles for accelerated development

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

jcleblanc
Download Presentation

API design principles for accelerated development

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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

  4. The Tradeoff Decision

  5. Developer efficiency task 1 Lower Perceived Latency Lowering perceived latency for developers

  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

  8. Separation of Concerns

  9. Stateless System Latency Issues A + B A + C Data Duplication

  10. Caching for Latency Reduction

  11. Developer efficiency task 2 Not Hindering with HTTP Use HTTP properly – standard request and response types

  12. What’s the Tradeoff?

  13. Requests and Responses GET / PUT / POST / DELETE have specific actions Proper status codes and error responses

  14. Descriptive Messaging Don’t do This {"error": "error 10008"} Do This HTTP/1.1 400 Bad Request Content-Length: 35 {"message":"Problems parsing JSON"}

  15. Useful Responses on Rate Limiting 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

  16. Don’t Want to Use Boring Responses? Use Status Cats! http://httpcats.herokuapp.com/

  17. Allowing HTTP Overriding Injecting PUT / DELETE methods when HTTP client only supports GET / POST curl -i -X POST https://api.sandbox.paypal.com/v1/payments/ \ -H "Content-Type:application/json" \ -H "X-HTTP-Method-Override: PUT"

  18. Action Automation

  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 You make an API request curl -v -X GET https://api.sandbox.paypal.com/v1/payments/authoriz ation/2DC87612EK520411B \ -H "Content-Type:application/json" \ -H "Authorization:Bearer ENxom5Fof1KqAffEsXtx1HTEK__KVdIsaCYF8C"

  26. "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" } ]

  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 OpenID Connect CORS Server-side SDKs Client-side SDK

  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? Site sends Origin header to server 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 ...

  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. URL Structure, Verbs, and Nouns GET POST POST DELETE /refund /payment /sale /payment GET POST POST DELETE /issueSingleRefund /getSinglePayment /setNewSingleSale /addNewSinglePayment

  39. Representations on Update / Create Send enough detail to not have to make another request to the API { "id": "PAY-17S8410768582940NKEE66EQ", "create_time": "2013-01-31T04:12:02Z", "update_time": "2013-01-31T04:12:04Z", "state": "approved", "intent": "sale", "payer": {...}, "transactions": [{...}], "links": [{...}] }

  40. Bringing it all Together API architecture is all about tradeoffs You are not making a perfect system, you are making a perfect system for your developers

  41. Thanks! Questions? http://slideshare.net/jcleblanc Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism PayPal North America

More Related