ReST APIs @ PyCon India, 2015

Transcript

1. ReST APIs What, Why and How? A. S. L. Devi PyCon India, 2015
2. What is an API programmable interface (to web services) Specifies the request and response formats for the communication between a client and a server.
3. Why? • Public APIs - services through API - glues best of several languages / technologies - AWS, Stripe, ElasticSearch, Twitter, GrapheneDB etc • Private APIs - same service offered in different UIs - a mobile app, a web app, desktop app - Slack, FaceBook etc
4. • Resources • URLs (Uniform Resource Locators) • HTTP - methods and response codes ReST - Representational State Transfer
5. Each resource is identified by a URL. /customers /customers/5 /customers/5/orders /customers/5/orders/42 /customers/5/orders?completed=true /customers/5/orders?completed=true&page=1 ReST - Resources
6. ReST - HTTP Verbs • GET - Retrieve a resource • POST - Create a resource • PUT - Create/update a resource • DELETE - Delete a resource GET, PUT and DELETE are idempotent.
7. • simple • consistent across - one way of doing things • backward compatible • HATEOS - linked documents • Well documented :) How should a ReST API be?
8. * taken from “Building Web APIs with Flask” with thanks to Miguel Grinberg
9. $ curl -XGET http://api.x.com/v1/customers HTTP/1.1 200 OK Content-Type: application/json { "customers": [] } $ curl -XGET http://api.x.com/v1/customers/1 { “name”: “Alice”, “links”: { “orders”: http://api.x.com/customers/1/orders “self”: http://api.x.com/customers/1 }} CRUD: Create Read Update Delete $ curl -XPOST http://api.x.com/v1/customers - d “name=Alice” HTTP/1.1 201 CREATED Content-Type: application/json Location: http://api.x.com/ customers/1 {} $ curl -XPUT http://api.x.com/v1/customers/1 -d “name=Bob” HTTP/1.1 200 OK $ http DELETE http://api.x.com/customers/1 HTTP/1.1 204 No Content
10. HATEOS - Linked documents $ curl -XGET http://api.x.com/v1/customers/1 { “name”: “Alice”, “links”: { “self”: “http://api.x.com/v1/customers/1, “orders”: “http://api.x.com/v1/customers/1/orders”, } }
11. More HATEOS $ curl -XGET http://api.x.com/v1/customers/1/orders/10 { “links”: { “self”: “http://api.x.com/v1/orders/10”, “customer”: “http://api.x.com/v1/customers/1” }, “orders”: [{ “date”: 2015-01-01-00:00:09Z, “items”: [ {“quantity”: 2, “product”: “XXX-1”}, {“quantity”: 3, “product”: “XYY-42”}, ] ]} }
12. How to choose a library to build ReST API • Data validation • Authentication & Authorization • Not tightly coupled with ORM or database • Pagination, rate limits, filters etc.
13. Authentication & Authorization - no assumptions of the client side - global authentication - Authorization header - Basic Authentication - Token-Based - HMAC based
14. • http://restful-api-design.readthedocs.org/en/latest/ • http://restcookbook.com/ • http://player.oreilly.com/videos/9781491911938 • http://jsonapi.org References
15. Questions
16. Thank You ! @asldevi