As you go into the cloud, the applications you are building will often be built on service-oriented architectures that communicate through RESTful APIs. Where API design and development used to be an uncommon thing, today it has become a basic application requirement. George Reese will cover the basic considerations in designing and implementing an API for your applications. George Reese is the author of a number of technology books and a regular speaker on RESTful APIs, cloud computing, Java, and database systems. His most recent books are The REST API Design Handbook and O’Reilly’s Cloud Application Architectures. Professionally, he is the Executive Director of Cloud Computing at Dell as a result of Dell's recent acquisition of Enstratius, a company George co-founded. George has also led a number of Open Source projects, including several MUD libraries and the Imaginary Home home automation libraries for Java. He is also the primary maintainer of Dasein Cloud, a cloud abstraction API for Java. George holds a BA from Bates College in Maine and an MBA from the Kellogg School of Management at Northwestern University.

1. RESTful API Design
George Reese, Senior Distinguished Engineer!
3 December 2013

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
2
Copyright (c) 2013 Dell, Inc.
Dell Software

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
3
Copyright (c) 2013 Dell, Inc.
Dell Software

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
4
Copyright (c) 2013 Dell, Inc.
Dell Software

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
5
Copyright (c) 2013 Dell, Inc.
Dell Software

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
6
Copyright (c) 2013 Dell, Inc.
Dell Software

7. A sample domain model
7
Copyright (c) 2013 Dell, Inc.
Dell Software

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 autodiscovery!
– Allows for a flexible, changeable set of resource
relationships!
• I prefer /Server/<sid>
8
Copyright (c) 2013 Dell, Inc.
Dell Software

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
9
Copyright (c) 2013 Dell, Inc.
Dell Software

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
10
Copyright (c) 2013 Dell, Inc.
Dell Software

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
11
Copyright (c) 2013 Dell, Inc.
Dell Software

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)
12
Copyright (c) 2013 Dell, Inc.
Dell Software

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
13
Copyright (c) 2013 Dell, Inc.
Dell Software

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
14
Copyright (c) 2013 Dell, Inc.
Dell Software

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
15
Copyright (c) 2013 Dell, Inc.
Dell Software

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
16
Copyright (c) 2013 Dell, Inc.
Dell Software

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
17
Copyright (c) 2013 Dell, Inc.
Dell Software

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)
18
Copyright (c) 2013 Dell, Inc.
Dell Software

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
19
Copyright (c) 2013 Dell, Inc.
Dell Software

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
20
Copyright (c) 2013 Dell, Inc.
Dell Software

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)
21
Copyright (c) 2013 Dell, Inc.
Dell Software

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
22
Copyright (c) 2013 Dell, Inc.
Dell Software

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
23
Copyright (c) 2013 Dell, Inc.
Dell Software

24. Questions?
Twitter:
@GeorgeReese
!
Email:
George_Reese@dell.com
24
Copyright (c) 2013 Dell, Inc.
Dell Software