Is Your REST API RESTful? - PyCon 2015

(Presented at PyCon 2015)
Watch here: https://www.youtube.com/watch?v=pZYRC8IbCwk

Writing a fully complaint REST API is hard, so hard it is too common for APIs to violate one or more of the REST architectural principles. In this talk I will describe the six REST principles, and I will tell you what happens if you don't follow them.

Transcript

1. Is your REST API RESTful? Miguel Grinberg @miguelgrinberg PyCon 2015
2. Who Am I? • I work for Rackspace as an OpenStack engineer. • I write about Flask, REST APIs, Robotics and more on my blog: http://blog.miguelgrinberg.com. • I am the author of a few open source Flask extensions: Flask-HTTPAuth, Flask-SocketIO, Flask-Migrate, etc. • I’m the author of the book Flask Web Development, and a few Flask training videos and webcasts, all for O’Reilly Media.
3. What does RESTful mean? • To be RESTful, an API must comply with the six constraints of REST. ◦ To my knowledge, there are no well known APIs that do it! ◦ Nobody agrees on what REST compliance exactly means. • APIs can still benefit greatly from partial support of the REST principles. Is Your REST API RESTful?
4. The Six REST Constraints • Client-Server • Stateless • Cache • Uniform Interface • Layered System • Code-On-Demand Easy Easy Hard Hard Medium Medium Is Your REST API RESTful?
5. Code-On-Demand (1/6) • This is the only optional REST principle; do it or don’t, it’s OK anyway! • Clients can receive executable code to run in their context as response to requests. • Not very practical (how does the API know what kind of code the client can execute?) Is Your REST API RESTful?
6. Client-Server (2/6) Is Your REST API RESTful?
7. Client-Server (2/6) Is Your REST API RESTful?
8. Layered System (3/6) Is Your REST API RESTful?
9. Layered System (3/6) Is Your REST API RESTful?
10. Cache (4/6) Is Your REST API RESTful?
11. Cache (4/6) Is Your REST API RESTful?
12. Stateless (5/6) • Sessions make scaling servers more difficult. • What about cookies? Nope. • Clients must authenticate with every request. • Always use secure HTTP! Is Your REST API RESTful?
13. Uniform Interface Identification of Resources (5.25/6) • Resources are all the entities in the domain of the application ◦ Customers, products, invoices, etc. • Each resource has a unique identifier URL ◦ Example: http://example.com/api/v2/jobs/324 • Collections of resources also have identifiers ◦ Example: http://example.com/api/v2/jobs/ Is Your REST API RESTful?
14. Uniform Interface Resource Representations (5.50/6) • Clients do not have direct access to resources; they only see their representations. • The server can provide representations in different formats (content types). ◦ Examples: JSON, XML, etc. • Clients perform all operations on resource representations. Is Your REST API RESTful?
15. Uniform Interface Self-Descriptive Messages (5.75/6) • Clients send HTTP requests and receive HTTP responses: ◦ Operation is given in the request method ◦ Target resource in request URL ◦ Authentication headers provide credentials ◦ Content-Type/Accept headers define media types ◦ Resource representation in body, when appropriate ◦ Operation result is in the response status code Is Your REST API RESTful?
16. Uniform Interface Hypermedia (HATEOAS) (6/6) • Clients do not know any resource URLs in advance except for the root URL of the API. • Resource URLs are discovered through links provided in resource representations. Is Your REST API RESTful?
17. Demo Time! https://github.com/miguelgrinberg/api-pycon2015
18. • Nah, I’m just kidding :-) • Python and Flask make it easy, even fun! Is Your REST API RESTful? @api.route('/classes/', methods=[‘GET’]) @etag @json @collection(Class) def get_classes(): return Class.query Easy Conclusion: REST Is Hard
19. @miguelgrinberg Thank You!