Building an API with Django and Django REST Framework
- 1. Building an API with Django and Django REST Framework PyTennessee 2016
- 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 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 Let’s build an API!
- 6. 6 Who’s with us so far?
- 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 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 Ok, let’s get started.
- 10. 10 Planning
- 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 Wait, isn’t CRUD bad? And why do I need REST already?
- 13. 13 CRUD • your basic database operations: • CREATE • READ • UPDATE • DELETE
- 14. 14 HTTP • your basic HTTP request methods: • POST • GET • PUT (and/or PATCH) • DELETE
- 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 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 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 Be as logically consistent as humanly possible
- 19. 19 Models git checkout -b models models
- 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 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 Serializers git checkout -b serializers serializers
- 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 Generic Views git checkout -b generic_view generic_view
- 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 Generic Views • basic GenericAPIView • composable with mixins • most common options pre-defined: • ListCreateView • RetrieveUpdateDestroyView • others...
- 27. 27 View Sets git checkout -b view_set view_set
- 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 URL Routing
- 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 URL Routing • if you’re using ViewSets, do the following: router = routers.DefaultRouter() router.register(r'card', CardViewSet) urlpatterns = router.urls
- 32. 32 “Browsable” API git checkout -b browsable_api browsable_api
- 33. 33 “Browseable” API • Let’s you experiment with your API via a browser
- 34. 34 Testing
- 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
- 38. 38 (Hopefully)
- 39. 39 Resources • http://www.django-rest-framework.org • https://docs.djangoproject.com • https://virtualenv.readthedocs.org • https://github.com/vokal/deckbuilder-api