Rest api design by george reese

RESTful API DesignGeorge Reese, Senior Distinguished Engineer!3 December 2013

Dell SoftwareCopyright (c) 2013 Dell, Inc.�2

My Background

•Co-founder of Enstratius!–Acquired by Dell in May 2013!

•Creator of Dasein Cloud!• Open Source Java cloud abstraction API

(https://github.com/greese/dasein-cloud)!• Interacts with nearly 2 dozen cloud APIs!

• Author of The Rest API Design Handbook


Historically, REST APIs suck•Rarely a core focus of effort in a system!• SOAP has been the more common web

services choice!– Very little design thought put into SOAP APIs!–WSDL is evil (so is WADL)!

•Often a task pawned off on some unsuspecting junior programmer!–Often following everyone else’s bad examples


So you want to write an API?

• Start with the API as your primary interface!– User interfaces and language bindings come later!– Any other approach for a cloudy system is doing it

wrong!•HTTP is the specification!– Don’t get creative on verbs, verb usage, or HTTP

status codes!– Authentication is the only valid point of deviation!– You worry about: transactions, query parameters,

headers, and payloads


You are not the judge of use cases

• A REST API enables…!–…people who are not you!–…to enhance the system you have built!–…in ways you cannot imagine!–…or in ways for which you lack resources!

•Unlike SOAP and language bindings, REST APIs are not judgmental!!– So don’t insert your judgment into the process


The domain model•HTTP is a resource-focused transport

protocol!– A RESTful approach thus models resources first!

• Identify the things that make up your system and their relationships!– Use a UML tool if you want; I use a white board!

•Relationships should be loosely coupled


A sample domain model


Mapping to endpoints• /Region/<rid>/Zone/<zid>Server/<sd>!– Easiest approach for auto-discovery of API!– Implies a very rigid hierarchy!

• /Server/<sid>!– Requires a higher level mechanism for auto-

discovery!– Allows for a flexible, changeable set of resource

relationships!• I prefer /Server/<sid>


Many to many relationships• In this example, Server <-> User is m2m!•Who owns the relationship?!– Server? !– User?!– Both?!

• Sometimes relationships have their own attributes (for example, User role)!• A change to one part of the relationship may

need reflecting in the other part


Use cases•Given the resources that exist in the

domain, what use cases will you support?!• Focus on CRUD operations, not

transactions!– You likely modeled transactions for your underlying

system!– But, your objective here is to support use cases not

currently implemented in your underlying system!• Functionality first, optimize later


Example use cases for Server• List servers with or without search criteria!•Get the details for a specific server!• Provision a new server in a target zone!• Terminate an existing server!• Stop an existing server!• Add user shell access to a server!•Remove user shell access to a server


Authentication model• There are dozens of authentication models

for REST APIs!•George’s REST authentication principles!–Must support authentication over plaintext!–Must easy to use across a number of programming

languages!– Should support the common interaction models for

your target client bases!–Must support credentials specific to each distinct

application consuming the API (revokable)


Authentication options•HTTP!– HTTP Basic and HTTP Digest!– Digital certificates!

•Non-HTTP!– Credentials in payload!– Secure token service!– Request signing!

•Recommendation!–OAuth 2 or request signing, depending on API


Error model•Use HTTP error codes only!– HTTP allows customized error codes within the

specified error classes!– But I’ve never seen that add any value!– Mostly I’ve seen people get the error classes wrong!

– 2xx -> it’s all good!– 3xx -> do something else!– 4xx -> client messed up!– 5xx -> server messed up


Resource modeling• XML vs JSON!– Don’t pick sides, support both!– HTTP is built around the idea that a single resource

has multiple possible representations, take advantage of that feature!

•Marshaling!– Do not tightly bind the RESTful resources to

underlying objects!• Pick your identifier scheme carefully


Read operations•GET (Always GET) (I mean it, always)!•Challenge with READs:!– Different use cases require different levels of detail

about a resource!– Different levels of detail have different impacts on

system performance!• Enable the client to specify the level of detail

in which it is interested!– ID+status, one level, or deep


Caching•Caching can help API performance, but it

comes with a price!•Caching can be a really good idea or a

really bad idea depending on your problem domain!– Caching server state -> bad idea!– Caching region state -> good idea!

•Clients get very angry when they regularly receive cached results that are wrong


Paging•HTTP is not the best protocol for very large

data sets!• Paging enables you to split results across

multiple GET requests!– because of the raw size of the response body!– or the amount of time the server takes to assemble

the results!•Design pagination in a manner transparent

to the client (via header directives)


Write operations• POST, DELETE, PUT!– POST -> new resource is created!– DELETE -> existing resource is deleted!– PUT -> an existing resource is changed!

•What about PATCH?!• Payloads!– Update directive + data matching GET format!

•Nonces recommended


Asynchronous operations• Sometimes an action takes a long time to

process and will potentially time out for a given HTTP call!• An asynchronous approach enables your

API call to return immediately and have the client track the process of the operation


Asynchronous operations (cont)• An operation is neither synchronous or asynchronous !• This is an implementation decision!• Use status codes to indicate what happened!

• 201 Created (synchronous)!• Body: at least an ID for a newly created object !

• 202 Accepted (asynchronous)!• Body: identifying information for a job/task to track!

• 204 No Content (synchronous)


Resource limiting• Throttling is generally a terrible idea!– Remember, your job is not to sit in judgment over a

customer’s use cases!• The primary job of throttling is to identify and

mitigate denial of service attacks or broken client code!• Avoid unilateral throttling!• Tell the client explicitly in the error response!•Give the client retry directives


Documentation• A REST API should be auto-discoverable!– I should be able to point my browser at your API

URL and start discovering it!– An HTTP request at an endpoint with a desire for

HTML content should be treated as a documentation request!

•Document authentication, query parameters, headers, and payload formats!• Provide functional examples with real data


Questions?Twitter:

@GeorgeReese !

Email:[email protected]

Rest api design by george reese

Documents

dell software

server user

server11copyright c

process5copyright c

deep16copyright c

coupled6copyright c

server messed up14copyright

different use cases