api design principles for accelerated development

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)