Building RESTful APIs

4,004 views

Published on

Fundamentals of building a Restful API with Django and django-rest-framework. Intended for new developers interested in developing a REST API for their applications. Basic knowledge of Python is nice to have, but the concepts are transferable.

Presented at Vancouver Python Day 2013.

Published in: Technology
0 Comments
13 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,004
On SlideShare
0
From Embeds
0
Number of Embeds
128
Actions
Shares
0
Downloads
86
Comments
0
Likes
13
Embeds 0
No embeds

No notes for slide

Building RESTful APIs

  1. 1. Building RESTful APIs Vancouver Python Day November 16, 2013 Ganesh Swami www.silota.com
  2. 2. Hi • Programming professionally for 10+ years • x86 assembly, STL, boost, python-boost, python ! • Built emacs-­‐wiki-­‐blog: first blogging engine for Emacs!
  3. 3. SILOTA • Search As A Service • • full stack: crawling, indexing, retrieving, tag deployment Python shop: • • ansible   • sentry   • django   • • pelican   django-­‐rest-­‐framework   In beta testing: love more feedback!
  4. 4. APIs: What & Why
  5. 5. What is an API? Application Programming Interface ! An API is the interface implemented by an application which allows other applications to communicate with it.
  6. 6. What is an API? communicate
  7. 7. What is REST? • REpresentational State Transfer • logical resources manipulated with HTTP verbs • modern best practice • wide adoption • contrast with SOAP
  8. 8. Why build an API? • explosion of devices connected to the internet • can be a company’s greatest asset • bizdev 2.0: internal developers, consultants, partners, customers
  9. 9. Sample APIs • aws • dropbox • instagram • pinterest • github • stripe • salesforce • parse • …
  10. 10. Source: Mary Meeker’s Internet Trends 2013
  11. 11. APIs: How
  12. 12. Top 3 qualities • Intuitive • • no surprises, easy to learn Documented • • • simple answers to simple questions references, tutorials & quick starts Opinionated • camelCase, ids, responses, pagination, etc.
  13. 13. Resources, Status Codes & Errors
  14. 14. Resources • Nouns, not verbs • Coarse grained, not fine grained • example: let’s build a document datastore!
  15. 15. Smells like RPC • /getDocument   • /getAllDocuments   • /createDocument   • /updateDocument   • /deleteDocument
  16. 16. Smells like RPC • /getDocument   • /getAllDocuments   • /createDocument   • /updateDocument   • /deleteDocument This is a bad example. ! Don’t do this!
  17. 17. Embrace HTTP • GET,  POST,  PUT,  PATCH,  DELETE   ! • Explorable with simple tools
  18. 18. Embrace HTTP GET  /document GET  /document/19 POST  /document Retrieve all documents Retrieve a specific document #19 Create a new document PUT  /document/19 Update an existing document #19 DELETE  /document/19 Delete an existing document #19
  19. 19. Bipartite graph /documents /documents/:id GET error POST PUT error PATCH error DELETE …
  20. 20. Status Codes 2xx OK, created, all good, carry on 4xx User error: bad API key, malformed data, item not found, etc. 5xx Server error
  21. 21. Errors • Errors • as descriptive as possible • developers are your customers • never naked 4xx/5xx HTTP errors
  22. 22. Errors <xml  version="1.0"?>   <Error>          <Message>A  server  error  has  occurred</Message>          <Description>Unknown  Error</Description>          <Id>1234</Id>   </Error> Just no.
  23. 23. Errors {      "code"  :  1234,      "message"  :  "Unsupported  media  type  ‘text/html’  in  request",      "description"  :  "Requests  need  to  have  the  Content-­‐Type  HTTP   header  set  to  ‘application/json’"   }
  24. 24. pip-install httpie
  25. 25. Best practices security base URLs serialization timestamps versioning caching gzip logging
  26. 26. Best practices security https all the way base URLs api.companyname.com serialization json timestamps ISO 8601 & UTC versioning /v1/ caching ETag & Last-Modified gzip always & pretty print responses logging if possible
  27. 27. Recap • https + gzip + json • draw bipartite graph of nouns and verbs • great documentation • no surprises
  28. 28. django-­‐rest-­‐framework
  29. 29. Why use a framework?
  30. 30. Myths • roll your own • use a ‘lightweight’ framework • too tied to django • too slow
  31. 31. Features • pagination • permission • authentication • serialization • throttling • data validation • proper HTTP response handling
  32. 32. Magic formula: Mixins Views Authentication Permissions Throttling CreateAPIView Token Any SimpleRate ListAPIView Session Token AnonRate RetrieveAPIView OAuth Authentication DeleteAPIView
  33. 33. Four step formula 1. create the model 2. write the serializer 3. write the view 4. configure the urls
  34. 34. References • How to Design a Good API and Why it Matters: • • Best Practices for Designing a Pragmatic RESTful API • • http://www.vinaysahni.com/best-practices-for-a-pragmaticrestful-api REST worst practices: • • http://lcsd05.cs.tamu.edu/slides/keynote.pdf http://jacobian.org/writing/rest-worst-practices/ http://django-rest-framework.org/
  35. 35. Keep in touch! Ganesh Swami! www.silota.com ganesh@silota.com @gane5h

×