Is your REST API RESTful? Miguel Grinberg @miguelgrinberg PyCon 2015

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.

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?

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?

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?

Client-Server (2/6) Is Your REST API RESTful?

Client-Server (2/6) Is Your REST API RESTful?

Layered System (3/6) Is Your REST API RESTful?

Layered System (3/6) Is Your REST API RESTful?

Cache (4/6) Is Your REST API RESTful?

Cache (4/6) Is Your REST API RESTful?

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?

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?

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?

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?

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?

Demo Time! https://github.com/miguelgrinberg/api-pycon2015

● 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

@miguelgrinberg Thank You!