Rest api design by george reese
- 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: [email protected] 24 Copyright (c) 2013 Dell, Inc. Dell Software