API design principles for accelerated development
-
Upload
jonathan-leblanc -
Category
Technology
-
view
1.848 -
download
2
description
Transcript of API design principles for accelerated development
![Page 1: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/1.jpg)
API Design PrinciplesFor Accelerated Development
Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism
(NA)
![Page 2: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/2.jpg)
The Exploration of API Design
Blank Slate Constraints
![Page 3: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/3.jpg)
Building APIs for Developers
![Page 4: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/4.jpg)
The Tradeoff Decision
![Page 5: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/5.jpg)
Developer efficiency task 1
Lowering perceived latency for developers
Lower Perceived Latency
![Page 6: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/6.jpg)
What’s the Tradeoff?
System Layering
Result Caching
![Page 7: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/7.jpg)
Layering the System
Encapsulates legacy systems
Simplified components
Better load balancing abilities
Systems can evolve independently
![Page 8: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/8.jpg)
Separation of Concerns
![Page 9: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/9.jpg)
Stateless System Latency Issues
Data Duplication
A + B
A + C
![Page 10: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/10.jpg)
Caching for Latency Reduction
![Page 11: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/11.jpg)
Developer efficiency task 2
Use HTTP properly – standard request and response types
Not Hindering with HTTP
![Page 12: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/12.jpg)
What’s the Tradeoff?
![Page 13: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/13.jpg)
Requests and Responses
GET / PUT / POST / DELETE have specific actions
Proper status codes and error responses
![Page 14: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/14.jpg)
Don’t do This{"error": "error 10008"}
Do ThisHTTP/1.1 400 Bad RequestContent-Length: 35
{"message":"Problems parsing JSON"}
Descriptive Messaging
![Page 15: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/15.jpg)
X-Rate-Limit-LimitNumber of requests allowed in current period
X-Rate-Limit-RemainingNumber of remaining requests in current period
X-Rate-Limit-ResetNumber of seconds left in current period
Useful Responses on Rate Limiting
![Page 16: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/16.jpg)
Use Status Cats! http://httpcats.herokuapp.com/
Don’t Want to Use Boring Responses?
![Page 17: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/17.jpg)
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
![Page 18: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/18.jpg)
Action Automation
![Page 19: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/19.jpg)
What’s the Tradeoff?
Payload Size Code Length
![Page 20: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/20.jpg)
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
![Page 21: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/21.jpg)
To Version or Not to Version
![Page 22: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/22.jpg)
Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via representations
Self descriptive messages
Hypermedia as the engine of application state
![Page 23: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/23.jpg)
How we Normally Consume APIs
![Page 24: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/24.jpg)
Using HATEOAS to Automate
![Page 25: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/25.jpg)
How HATEOAS Works
curl -v -X GET https://api.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ENxom5Fof1KqAffEsXtx1HTEK__KVdIsaCYF8C"
You make an API request
![Page 26: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/26.jpg)
"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" }]
![Page 27: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/27.jpg)
Developer efficiency task 2Secure Data Resources
![Page 28: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/28.jpg)
What’s the Tradeoff?
Security Usability
![Page 29: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/29.jpg)
Some Security Models
Proprietary Solution
Basic Authentication
OAuth 1.0a
OAuth 2 / OpenID Connect
Cross-Origin Resource Sharing (CORS)
![Page 30: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/30.jpg)
Keeping Things Hidden
Token based auth mechanismOAuth: Client Secret
Basic Auth: Password
API request action to reaction mapping
A schematic for how data forces site changes
![Page 31: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/31.jpg)
A Modern Approach
CORS
Client-side SDK
OpenID Connect
Server-side SDKs
![Page 32: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/32.jpg)
Working on the Server Side SDKs
Secure Token Management
Separation of Concerns
Simplified Development
![Page 33: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/33.jpg)
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
![Page 34: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/34.jpg)
Can you use it?
http://caniuse.com/cors
![Page 35: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/35.jpg)
How Does it Work?
OPTIONS /v1/oauth2/token HTTP/1.1Origin: http://jcleblanc.comAccess-Control-Request-Method: PUTAccess-Control-Request-Headers: X-Custom-HeaderHost: api.sandbox.paypal.comAccept-Language: en-USConnection: keep-alive...
Site sends Origin header to server
![Page 36: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/36.jpg)
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
Access-Control-Allow-Headers: X-Custom-Header
Content-Type: text/html; charset=utf-8
![Page 37: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/37.jpg)
Developer efficiency task 4
Offload complexity to the implementing provider
Offload Complexity
![Page 38: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/38.jpg)
The Complexities
Authentication / Authorization
Legacy API support
Working between versioning
API changes that break implementations
Reduction in latency
![Page 39: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/39.jpg)
GET /paymentPOST /salePOST /paymentDELETE /refund
GET /getSinglePaymentPOST /setNewSingleSalePOST /addNewSinglePaymentDELETE /issueSingleRefund
URL Structure, Verbs, and Nouns
![Page 40: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/40.jpg)
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
![Page 41: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/41.jpg)
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
![Page 42: API design principles for accelerated development](https://reader036.fdocuments.us/reader036/viewer/2022062511/54c843f64a795985748b4607/html5/thumbnails/42.jpg)
Thanks! Questions?http://slideshare.net/jcleblanc
Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism
(NA)