Downloaded 21 times
!["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/2014febconfoodesigningjavascriptapis-140228090705-phpapp02/75/Designing-JavaScript-APIs-34-2048.jpg)
![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": [{...}] }](https://image.slidesharecdn.com/2014febconfoodesigningjavascriptapis-140228090705-phpapp02/75/Designing-JavaScript-APIs-37-2048.jpg)
Uploaded byJonathan LeBlanc
Designing JavaScript APIs
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.
Designing JavaScript APIs
- 1. Designing JavaScript APIs JonathanLeBlanc (@jcleblanc) Global Head of Developer Evangelism at PayPal
- 2.
- 3.
- 4. What JavaScript CanFeel Like
- 5.
- 6.
- 7. Keeping Private KeysPrivate
- 8. Not Providing aHacked Experience
- 9. How Did WeUsed to Do It?
- 10.
- 11. Flash / iFrameProxies
- 12.
- 13.
- 14. A Modern Approach OAuth2 Tight Access Control CORS Easy Access Control
- 15. OAuth 2 UserAgent Flow
- 16. Redirect the Userto 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 AccessToken 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 APIResources 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 AccessControl
- 23. Cross Origin Issuesand 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 useit? http://caniuse.com/cors Support: 79.42% Partial support: 8.84% Total: 88.26%
- 25. How Does itWork? 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 itWork? 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’ BitO’ Automation
- 28. Uniform Interface Sub-Constraints ResourceIdentification Resources must be manipulated via representations Self descriptive messages Hypermedia as the engine of application state
- 29. Uniform Interface Sub-Constraints ResourceIdentification Resources must be manipulated via representations Self descriptive messages Hypermedia as the engine of application state
- 30.
- 31. How we NormallyConsume APIs
- 32. Using HATEOAS toAutomate
- 33. How HATEOAS Works Youmake 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.
- 35. How do weMake it Work with JS? Open Path Library (what to do next) Hierarchy of Requests
- 36.
- 37. The System Shouldbe 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 Manipulatea concept (e.g. payment) with the intended state
- 39. Chaining Actions The firstrequest 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 needsto 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
Editor's Notes
- #8 Keeping private keys private
- #24 JSONP can cause XSS issues where the external site is compromised, CORS allows websites to manually parse responses to ensure security
- #27 Behind the server scene, the server looks up the application in their records to verify that the application matches what is on file against the application location making the request
- #31 Hypermedia as the engine of application state
- #36 How do you improve this structure to make it useable for automation?
- #37 Resources must be manipulated via representations. This goes back to the stateless principles
- #40 REST principle of using objects applied to chaining multiple objects together