REST Best Common Practices D. Keith Casey Jr [email protected] @CaseySoftware 

Who am I? 

Who am I? Clarify.io - The API for businesses to build apps that Search and Understand their Audio & Videos 

Who am I? http://TheAPIDesignBook.com 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

Assumptions • APIs are an important part of your job • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private 7 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

• We had single stack (monolith) applications • Self-contained • Completely independent • Built by humans for humans • Promoted duplication of components In the Beginning.. 

In the Beginning.. 

• Web Services • SOAP • XML-RPC • XML over HTTP • Other random junk.. A little later.. 

A little later.. 

• Six Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand A little more sanity: REST 

“Strictly RESTful” 14 REST is not a Standard. 

What REST is not… 15 • Pretty URLs • XML over HTTP • JSON over HTTP 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

Client-Server • We get this one • By separating them, we can vary them • Web & database servers • Scalability & Reliability 

Stateless • Each request stands on its own • This is where we struggle • Sessions, cookies, etc • Synchronization • Sticky sessions 

Stateless curl https://api.clarify.io/v1/search? query=dorothy \ --header "Authorization: Bearer myapikey" 

Stateless - Why? • It’s WEB SCALE • Stability • Reliability • Flexibility 

Cacheable • GET, PUT, and DELETE should be idempotent or “safe” • The word “safe” here means that if a given HTTP method is invoked 1 or N times, the resource remains the same after the 1st • POST.. stupid POST 

Cacheable • Within Clarify.io • /v1/bundles/ • GET {limit, iterator, embed} • POST {name, media_url, notify_url} • PUT n/a • DELETE n/a 

Cacheable • Within Clarify.io • /v1/bundles/{bundle_id} • GET {bundle_id, embed} • POST n/a • PUT {name, media_url, notify_url} • DELETE n/a 

Layered System • Don’t count on the Client and Server communicating directly • We use this on the web every day • Adds silent, invisible dependencies 

Layered System - Why? • Allows you to add intermediaries • Load balancers, caching • Logging, audit trails • Authentication & Authorization 

Skynet Day 26 https://www.twilio.com/engineering/2011/04/22/why-twilio- wasnt-affected-by-todays-aws-issues 

Code on Demand (optional) • A request doesn’t just retrieve a resource but also the code to act upon it • We don’t have to know or understand the code, just how to run it • Allows for flexibility and upgradability 

28 Ummm.. gmail? (or really, any Javascript on the web) Code on Demand (optional) 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

Uniform Interfaces • Four Principles • Identification of resources • Manipulation of resources through these representations • Self-descriptive messages • Hypermedia as the engine of application state (HATEOAS) 

Identification of Resources • Generally • /noun/id • /noun/action/id • But not required • /?n=noun&id=id • /?n=noun&page=n 

Manipulation of Resources • Within Clarify.io • /v1/bundles/ • /v1/bundles/{bundles_id}/insights • /v1/bundles/{bundles_id}/metadata • /v1/bundles/{bundles_id}/tracks • GET, POST, PUT, DELETE 

Self-Descriptive Messages • Each message should tell you • how to process itself; • how to request the next resource; • if that resource is cacheable. 

HATEOAS Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g. by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources beyond those described in representations previously received from the server. Ref: https://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services 

• Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources 

No Pun Intended • http://TheAPIDesignBook.com • http://videos.restfest.org • Anything by Mike Amundsen • Anything by Kin Lane 

D. Keith Casey Jr [email protected] @CaseySoftware REST Best Common Practices 

Go Buy This! http://TheAPIDesignBook.com