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