The document outlines key API design principles aimed at enhancing developer efficiency, including strategies for reducing latency, properly utilizing HTTP methods, and securing data resources. It emphasizes important practices such as using correct status codes, leveraging hypermedia as the engine of application state (HATEOAS), and adopting modern security models like OAuth. The document also highlights the importance of offloading complexity to providers and making thoughtful tradeoffs in API architecture to meet developers' needs.

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
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

8. Separation of Concerns

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

12. What’s the Tradeoff?

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

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
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. "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
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