Embed Size (px)
DESCRIPTION
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
Citation preview
API Design PrinciplesFor Accelerated Development
Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism
(NA)
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 independently
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 ThisHTTP/1.1 400 Bad RequestContent-Length: 35
{"message":"Problems parsing JSON"}
Descriptive Messaging
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
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" \
-H "X-HTTP-Method-Override: PUT"
Injecting PUT / DELETE methods when HTTP client only supports GET / POST
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 via HTTP Accept header
Double Rainbow: Discovery via HATEOAS
To Version or Not to Version
Uniform Interface Sub-Constraints
Resource Identification
Resources must be manipulated via representations
Self descriptive messages
Hypermedia as the engine of application state
How we Normally Consume APIs
Using HATEOAS to Automate
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
"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" }]
Developer efficiency task 2Secure 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 Sharing (CORS)
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
A Modern Approach
CORS
Client-side SDK
OpenID Connect
Server-side SDKs
Working on the Server Side SDKs
Secure Token Management
Separation of Concerns
Simplified Development
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
Can you use it?
http://caniuse.com/cors
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
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
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 implementations
Reduction in latency
GET /paymentPOST /salePOST /paymentDELETE /refund
GET /getSinglePaymentPOST /setNewSingleSalePOST /addNewSinglePaymentDELETE /issueSingleRefund
URL Structure, Verbs, and Nouns
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
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
Thanks! Questions?http://slideshare.net/jcleblanc
Jonathan LeBlanc (@jcleblanc) Head of Developer Evangelism
(NA)
