Download - 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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�3
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�4
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�5
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�6
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�7
A sample domain model
Dell SoftwareCopyright (c) 2013 Dell, Inc.�8
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>
Dell SoftwareCopyright (c) 2013 Dell, Inc.�9
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�10
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�11
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�12
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)
Dell SoftwareCopyright (c) 2013 Dell, Inc.�13
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�14
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�15
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�16
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�17
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�18
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)
Dell SoftwareCopyright (c) 2013 Dell, Inc.�19
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�20
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�21
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)
Dell SoftwareCopyright (c) 2013 Dell, Inc.�22
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�23
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
Dell SoftwareCopyright (c) 2013 Dell, Inc.�24
Questions?Twitter:
@GeorgeReese !
Email:[email protected]