Building an API with Django and Django REST Framework

1,039 views

Published on

A tutorial presented at PyTennessee 2016. Steps through the basics of building an API with Django using Django REST Framework.

Published in: Software

Building an API with Django and Django REST Framework

  1. 1. Building an API with Django and Django REST Framework PyTennessee 2016
  2. 2. 2 Hi, I’m Chris Foresman • Senior Systems Engineer at Vokal • Python mentor to all ages • Learned to program in BASIC on a TRS-80 circa 1986 • Love: karaoke, bourbon, brunch • I have a 3-yr-old at home @foresmac
  3. 3. 3 Hi, I’m Adam Bain • Systems Engineer at Vokal • Rehabilitated Java engineer via Python • Learned to program in BASIC circa 94 • Likes: Hockey, Craft Beer • I referee robotics competitions @adam_bain
  4. 4. 4 Let’s build an API!
  5. 5. 5 With Python!
  6. 6. 6 Who’s with us so far?
  7. 7. 7 If you want to follow along: • terminal access • a text editor: SublimeText, Atom, vim • or IDE, like PyCharm • ideally have virtualenv (or venv) • git
  8. 8. 8 If you want to follow along: • mkdir ~/tutorial • virtualenv ~/tutorial • cd ~/tutorial • source bin/activate • pip install django djangorestframework • git clone https://github.com/vokal/deckbuilder-api.git • git checkout -b base base
  9. 9. 9 Ok, let’s get started.
  10. 10. 10 Planning
  11. 11. 11 Planning • sketch out your data models • how will different things be represented? • think about what actions your API needs to support • will you be strictly RESTful, supporting only CRUD? • or, will your API be more expressive? • it’s up to you to strike a balance!
  12. 12. 12 Wait, isn’t CRUD bad? And why do I need REST already?
  13. 13. 13 CRUD • your basic database operations: • CREATE • READ • UPDATE • DELETE
  14. 14. 14 HTTP • your basic HTTP request methods: • POST • GET • PUT (and/or PATCH) • DELETE
  15. 15. 15 REST in a nutshell • your basic RESTful API: • CREATE = POST • READ = GET • UPDATE = PUT (and/or PATCH) • DELETE = DELETE FYI: REST stands for Representational State Transfer
  16. 16. 16 Common RESTful pattern • /object • POST data to this endpoint to create a new object • GET this endpoint to retrieve a list of objects • /object/:id • GET this endpoint to get details about a particular object • PUT or PATCH data to this endpoint to update that object • DELETE this endpoint to delete the object
  17. 17. 17 Pragmatic, not-strictly-RESTful patterns • /object/:id/action • Either POST data to this endpoint to perform some action, particularly if it results in new data being created, or • PUT to this endpoint to perform some action that doesn’t require any additional data, and typically modifies existing data but does not create new data objects • /object/noun • GET this endpoint to get some specific grouping or set of the objects
  18. 18. 18 Be as logically consistent as humanly possible
  19. 19. 19 Models git checkout -b models models
  20. 20. 20 Models • define objects that represent your data • map fields to database column types • handle DB magic for you (for the most part) • strive for “fat” models and “thin” views • give your models methods • for complicated creation, updating, etc, use managers
  21. 21. 21 Models • know your field types • CharField • IntegerField • BooleanField • DatetimeField • etc • fields also have parameters that affect database table creation and data validation • null=True, max_length=255, etc
  22. 22. 22 Serializers git checkout -b serializers serializers
  23. 23. 23 Serializers • this is the main gateway between your API and the world • typically: • validates input • converts JSON to Python dict • converts model instances to Python dicts • which can then be passed to model instances and saved to the database
  24. 24. 24 Generic Views git checkout -b generic_view generic_view
  25. 25. 25 Generic Views • class-based views • can be configured with basic attributes: • serializer • permissions_classes • queryset • or can use more dynamic config: • get_queryset() • get_serializer() • etc
  26. 26. 26 Generic Views • basic GenericAPIView • composable with mixins • most common options pre-defined: • ListCreateView • RetrieveUpdateDestroyView • others...
  27. 27. 27 View Sets git checkout -b view_set view_set
  28. 28. 28 View Sets • great for straightforward CRUD operations • can be extended with additional “detail” views • automagically handle URL routing generation • a lot of functionality for a little bit of code
  29. 29. 29 URL Routing
  30. 30. 30 URL Routing • just match a URL regex with a corresponding view • call as_view() on it, like so: url(r’^/card/?$’, ListCreateCardView.as_view(), name=’list-create-card’)
  31. 31. 31 URL Routing • if you’re using ViewSets, do the following: router = routers.DefaultRouter() router.register(r'card', CardViewSet) urlpatterns = router.urls
  32. 32. 32 “Browsable” API git checkout -b browsable_api browsable_api
  33. 33. 33 “Browseable” API • Let’s you experiment with your API via a browser
  34. 34. 34 Testing
  35. 35. 35 Testing • why does everyone hate it? • trust us, you’ll thank yourself later • generally “integration” tests cover most code • additional unit tests cover everything else • for Pete’s sake, learn to use mock
  36. 36. 36 You’ve got questions?
  37. 37. 37 We’ve got answers.
  38. 38. 38 (Hopefully)
  39. 39. 39 Resources • http://www.django-rest-framework.org • https://docs.djangoproject.com • https://virtualenv.readthedocs.org • https://github.com/vokal/deckbuilder-api
  40. 40. Thank you! PyTennessee 2016

×