Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
API Design Principles
For Accelerated Development
Jonathan LeBlanc (@jcleblanc)
Head of Developer Evangelism
PayPal North ...
The Exploration of API Design
Blank Slate Constraints
Building APIs for Developers
The Tradeoff Decision
Developer efficiency task 1
Lowering perceived latency for developers
Lower Perceived Latency
What’s the Tradeoff?
System Layering
Result Caching
Layering the System
Encapsulates legacy systems
Simplified components
Better load balancing abilities
Systems can evolve i...
Separation of Concerns
Stateless System Latency Issues
Data Duplication
A + B
A + C
Caching for Latency Reduction
Developer efficiency task 2
Use HTTP properly – standard request and
response types
Not Hindering with HTTP
What’s the Tradeoff?
Requests and Responses
GET / PUT / POST / DELETE
have specific actions
Proper status codes and error
responses
Don’t do This
{"error": "error 10008"}
Do This
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JS...
X-Rate-Limit-Limit
Number of requests allowed in current period
X-Rate-Limit-Remaining
Number of remaining requests in cur...
Use Status Cats! http://httpcats.herokuapp.com/
Don’t Want to Use Boring Responses?
Allowing HTTP Overriding
curl -i -X POST
https://api.sandbox.paypal.com/v1/payments/ 
-H "Content-Type:application/json" 
...
Action Automation
What’s the Tradeoff?
Payload Size Code Length
RESTful API Core Concepts
Honor HTTP request verbs
Use proper HTTP status codes
No version numbering in URIs
Return format...
To Version or Not to Version
Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via
representations
Self descripti...
How we Normally Consume APIs
Using HATEOAS to Automate
How HATEOAS Works
curl -v -X GET
https://api.sandbox.paypal.com/v1/payments/authoriz
ation/2DC87612EK520411B 
-H "Content-...
"links": [
{
"href":"https://api.sandbox.paypal.com/v1/payments/
authorization/6H149011U8307001M",
"rel":"self",
"method":...
Developer efficiency task 2
Secure Data Resources
What’s the Tradeoff?
Security Usability
Some Security Models
Proprietary Solution
Basic Authentication
OAuth 1.0a
OAuth 2 / OpenID Connect
Cross-Origin Resource S...
A Modern Approach
CORS
Client-side SDK
OpenID Connect
Server-side SDKs
Working on the Server Side SDKs
Secure Token
Management
Simplified
Development
Cross Origin Issues and Options
Access to other domains / subdomains is
restricted (same origin policy)
JSONP to request r...
Can you use it?
http://caniuse.com/cors
How Does it Work?
OPTIONS /v1/oauth2/token HTTP/1.1
Origin: http://jcleblanc.com
Access-Control-Request-Method: PUT
Host: ...
How Does it Work?
Server responds with matching
Access-Control-Allow-Origin header
Access-Control-Allow-Origin: http://jcl...
Developer efficiency task 4
Offload complexity to the implementing
provider
Offload Complexity
The Complexities
Authentication / Authorization
Legacy API support
Working between versioning
API changes that break imple...
GET /payment
POST /sale
POST /payment
DELETE /refund
GET /getSinglePayment
POST /setNewSingleSale
POST /addNewSinglePaymen...
Representations on Update / Create
{ "id": "PAY-17S8410768582940NKEE66EQ",
"create_time": "2013-01-31T04:12:02Z",
"update_...
API architecture is all about tradeoffs
You are not making a perfect system,
you are making a perfect system for your
deve...
Thanks! Questions?
http://slideshare.net/jcleblanc
Jonathan LeBlanc (@jcleblanc)
Head of Developer Evangelism
PayPal North...
Upcoming SlideShare
Loading in …5
×

of

API design principles for accelerated development Slide 1 API design principles for accelerated development Slide 2 API design principles for accelerated development Slide 3 API design principles for accelerated development Slide 4 API design principles for accelerated development Slide 5 API design principles for accelerated development Slide 6 API design principles for accelerated development Slide 7 API design principles for accelerated development Slide 8 API design principles for accelerated development Slide 9 API design principles for accelerated development Slide 10 API design principles for accelerated development Slide 11 API design principles for accelerated development Slide 12 API design principles for accelerated development Slide 13 API design principles for accelerated development Slide 14 API design principles for accelerated development Slide 15 API design principles for accelerated development Slide 16 API design principles for accelerated development Slide 17 API design principles for accelerated development Slide 18 API design principles for accelerated development Slide 19 API design principles for accelerated development Slide 20 API design principles for accelerated development Slide 21 API design principles for accelerated development Slide 22 API design principles for accelerated development Slide 23 API design principles for accelerated development Slide 24 API design principles for accelerated development Slide 25 API design principles for accelerated development Slide 26 API design principles for accelerated development Slide 27 API design principles for accelerated development Slide 28 API design principles for accelerated development Slide 29 API design principles for accelerated development Slide 30 API design principles for accelerated development Slide 31 API design principles for accelerated development Slide 32 API design principles for accelerated development Slide 33 API design principles for accelerated development Slide 34 API design principles for accelerated development Slide 35 API design principles for accelerated development Slide 36 API design principles for accelerated development Slide 37 API design principles for accelerated development Slide 38 API design principles for accelerated development Slide 39 API design principles for accelerated development Slide 40 API design principles for accelerated development Slide 41
Upcoming SlideShare
The API-Application Semantic Gap
Next
Download to read offline and view in fullscreen.

4 Likes

Share

Download to read offline

API design principles for accelerated development

Download to read offline

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

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

API design principles for accelerated development

  1. 1. API Design Principles For Accelerated Development Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism PayPal North America
  2. 2. The Exploration of API Design Blank Slate Constraints
  3. 3. Building APIs for Developers
  4. 4. The Tradeoff Decision
  5. 5. Developer efficiency task 1 Lowering perceived latency for developers Lower Perceived Latency
  6. 6. What’s the Tradeoff? System Layering Result Caching
  7. 7. Layering the System Encapsulates legacy systems Simplified components Better load balancing abilities Systems can evolve independently
  8. 8. Separation of Concerns
  9. 9. Stateless System Latency Issues Data Duplication A + B A + C
  10. 10. Caching for Latency Reduction
  11. 11. Developer efficiency task 2 Use HTTP properly – standard request and response types Not Hindering with HTTP
  12. 12. What’s the Tradeoff?
  13. 13. Requests and Responses GET / PUT / POST / DELETE have specific actions Proper status codes and error responses
  14. 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. 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. 16. Use Status Cats! http://httpcats.herokuapp.com/ Don’t Want to Use Boring Responses?
  17. 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
  18. 18. Action Automation
  19. 19. What’s the Tradeoff? Payload Size Code Length
  20. 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. 21. To Version or Not to Version
  22. 22. Uniform Interface Sub-Constraints Resource Identification Resources must be manipulated via representations Self descriptive messages Hypermedia as the engine of application state
  23. 23. How we Normally Consume APIs
  24. 24. Using HATEOAS to Automate
  25. 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
  26. 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. 27. Developer efficiency task 2 Secure Data Resources
  28. 28. What’s the Tradeoff? Security Usability
  29. 29. Some Security Models Proprietary Solution Basic Authentication OAuth 1.0a OAuth 2 / OpenID Connect Cross-Origin Resource Sharing (CORS)
  30. 30. A Modern Approach CORS Client-side SDK OpenID Connect Server-side SDKs
  31. 31. Working on the Server Side SDKs Secure Token Management Simplified Development
  32. 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. 33. Can you use it? http://caniuse.com/cors
  34. 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. 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. 36. Developer efficiency task 4 Offload complexity to the implementing provider Offload Complexity
  37. 37. The Complexities Authentication / Authorization Legacy API support Working between versioning API changes that break implementations Reduction in latency
  38. 38. GET /payment POST /sale POST /payment DELETE /refund GET /getSinglePayment POST /setNewSingleSale POST /addNewSinglePayment DELETE /issueSingleRefund URL Structure, Verbs, and Nouns
  39. 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. 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. 41. Thanks! Questions? http://slideshare.net/jcleblanc Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism PayPal North America
  • SeanYoo9

    Oct. 6, 2018
  • VaibhavPaliwal11

    Apr. 23, 2016
  • dash007

    Mar. 20, 2015
  • GoutamBagchi

    Apr. 5, 2014

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

Views

Total views

3,800

On Slideshare

0

From embeds

0

Number of embeds

134

Actions

Downloads

118

Shares

0

Comments

0

Likes

4

×