Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
RESTful API Design
George Reese, Senior Distinguished Engineer!
3 December 2013
My Background
• Co-founder of Enstratius!
– Acquired by Dell in May 2013!

• Creator of Dasein Cloud!
• Open Source Java c...
Historically, REST APIs suck
• Rarely a core focus of effort in a system!
• SOAP has been the more common web
services cho...
So you want to write an API?
• Start with the API as your primary interface!
– User interfaces and language bindings come ...
You are not the judge of use cases
• A REST API enables…!
– …people who are not you!
– …to enhance the system you have bui...
The domain model
• HTTP is a resource-focused transport
protocol!
– A RESTful approach thus models resources first!

• Ide...
A sample domain model

7

Copyright (c) 2013 Dell, Inc.

Dell Software
Mapping to endpoints
• /Region/<rid>/Zone/<zid>Server/<sd>!
– Easiest approach for auto-discovery of API!
– Implies a very...
Many to many relationships
• In this example, Server <-> User is m2m!
• Who owns the relationship?!
– Server? !
– User?!
–...
Use cases
• Given the resources that exist in the
domain, what use cases will you support?!
• Focus on CRUD operations, no...
Example use cases for Server
• List servers with or without search criteria!
• Get the details for a specific server!
• Pr...
Authentication model
• There are dozens of authentication models
for REST APIs!
• George’s REST authentication principles!...
Authentication options
• HTTP!
– HTTP Basic and HTTP Digest!
– Digital certificates!

• Non-HTTP!
– Credentials in payload...
Error model
• Use HTTP error codes only!
– HTTP allows customized error codes within the
specified error classes!
– But I’...
Resource modeling
• XML vs JSON!
– Don’t pick sides, support both!
– HTTP is built around the idea that a single resource
...
Read operations
• GET (Always GET) (I mean it, always)!
• Challenge with READs:!
– Different use cases require different l...
Caching
• Caching can help API performance, but it
comes with a price!
• Caching can be a really good idea or a
really bad...
Paging
• HTTP is not the best protocol for very large
data sets!
• Paging enables you to split results across
multiple GET...
Write operations
• POST, DELETE, PUT!
– POST -> new resource is created!
– DELETE -> existing resource is deleted!
– PUT -...
Asynchronous operations
• Sometimes an action takes a long time to
process and will potentially time out for a
given HTTP ...
Asynchronous operations (cont)
• An operation is neither synchronous or asynchronous !
• This is an implementation decisio...
Resource limiting
• Throttling is generally a terrible idea!
– Remember, your job is not to sit in judgment over a
custome...
Documentation
• A REST API should be auto-discoverable!
– I should be able to point my browser at your API
URL and start d...
Questions?
Twitter: 

@GeorgeReese
!

Email:

George_Reese@dell.com

24

Copyright (c) 2013 Dell, Inc.

Dell Software
Upcoming SlideShare
Loading in …5
×

Rest api design by george reese

25,977 views

Published on

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.

  • Be the first to comment

Rest api design by george reese

  1. 1. RESTful API Design George Reese, Senior Distinguished Engineer! 3 December 2013
  2. 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. 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. 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. 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. 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. 7. A sample domain model 7 Copyright (c) 2013 Dell, Inc. Dell Software
  8. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 24. Questions? Twitter: 
 @GeorgeReese ! Email:
 George_Reese@dell.com 24 Copyright (c) 2013 Dell, Inc. Dell Software

×