This document discusses best practices for designing JavaScript APIs. It covers topics like securing APIs using OAuth 2 and CORS for authorization, following HATEOAS principles to allow for automation by providing state transitions and links to next actions, and designing APIs to be stateless by sending complete representations in requests. The goal is to build APIs that are secure, easy to use and integrate, and allow developers to automate complex workflows.

1. Designing JavaScript APIs
Jonathan LeBlanc (@jcleblanc)
Global Head of Developer
Evangelism at PayPal

2. API? SDK?

3. Automation?

4. What JavaScript Can Feel Like

5. JavaScript Challenges

6. The Same-Origin Policy

7. Keeping Private Keys Private

8. Not Providing a Hacked Experience

9. How Did We Used to Do It?

10. Server-side Proxies

11. Flash / iFrame Proxies

12. Private Token Storage

13. Securing Resources

14. A Modern Approach
OAuth 2
Tight Access Control
CORS
Easy Access Control

15. OAuth 2 User Agent Flow

16. Redirect the User to Log In
Prepare the Redirect URI
Authorization Endpoint
client_id response_type (token)
scope
redirect_uri
Browser Redirect
Redirect URI

17. User Agent Flow: Redirect
var auth_uri = auth_endpoint +
"?response_type=token" +
"&client_id=" + client_id +
"&scope=profile" +
"&redirect_uri=" + window.location;
$("#auth_btn").attr("href", auth_uri);

18. Extract the Access Token
Fetch the Hash Mod
access_token
refresh_token
expires_in
Extract Access Token

19. User Agent Flow: Hash Mod
Extract the Access Token from the Hash
http://site.com/callback#access_token=rBEGu1FQr5
4AzqE3Q&refresh_token=rEBt51FZr54HayqE3V4a&
expires_in=3600
var hash = document.location.hash;
var match = hash.match(/access_token=(w+)/);

20. Get Privileged API Resources
Set Request Headers + URI
Resource Endpoint
Header: token type + access token
Header: accept data type
HTTPS Request

21. User Agent Flow: Get Resources
Making an Authorized Request
$.ajax({
url: resource_uri,
beforeSend: function (xhr) {
xhr.setRequestHeader('Authorization', 'OAuth ' + token);
xhr.setRequestHeader('Accept', 'application/json');
},
success: function (response) {
//use response object
}
});

22. CORS Easy Access Control

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

24. Can you use it?
http://caniuse.com/cors
Support: 79.42%
Partial support: 8.84%
Total: 88.26%

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

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

27. A Lil’ Bit O’ Automation

28. Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via
representations
Self descriptive messages
Hypermedia as the engine of application state

29. Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via
representations
Self descriptive messages
Hypermedia as the engine of application state

30. HATEOAS

31. How we Normally Consume APIs

32. Using HATEOAS to Automate

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

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

35. How do we Make it Work with JS?
Open Path Library
(what to do next)
Hierarchy of Requests

36. Object Chaining

37. The System Should be Stateless
Send complete object to only make 1 request
{ "id": "PAY-17S8410768582940NKEE66EQ",
"create_time": "2013-01-31T04:12:02Z",
"update_time": "2013-01-31T04:12:04Z",
"state": "approved",
"intent": "sale",
"payer": {...},
"transactions": [{...}],
"links": [{...}] }

38. Resources and Representations
Manipulate a concept (e.g. payment) with
the intended state

39. Chaining Actions
The first request builds the action object
Subsequent calls manipulate the object
var paymentObj =
getPreAuth(paymentID)
.getNextAction()
.processNext();
//build pay object
//next HATEOAS link
//process action

40. In Summation
Security needs to allow you to work the
browser security model
Always assume statelessness
Build to allow your developers to automate
complexities

41. Thanks! Questions?
http://slideshare.com/jcleblanc
Jonathan LeBlanc (@jcleblanc)
Global Head of Developer
Evangelism at PayPal