RESTful APIs and Django - Emad Mokhtar¶

Tags: python, django

(Summary of a talk at the Amsterdam python meetup)

Ehmad Mokhtar used Django a lot. And he loves web APIs: you can have many intergrations. You build one back-end and it can be used by many other services and front-ends. It is also core for microservices and “service oriented architectures”.

So: APIs = business! Without APIs, you have no intergrations. So often you won’t have as much business.

What is a RESTful API? It is an architectural style that uses HTTP: you work on URLs (“resources”) and you use HTTP verbs (“GET”, “DELETE”, “POST”).

If you build an API, developers are your API customers. So you need, for instance, great documentation. You need to keep that in mind all the time.

If you use django and you want to build an API: use django rest framework (DRF). DRF feels like django itself. It uses the ORM. And it is perhaps even better documented than Django itself.

A tip he has is to use two views per model. In django, you can have a separate list view, a delete view, a regular view, etc. In DRF you are best off having two:

• One for listing items and creating new ones. (/customers/)

  • GET: list of customers.

  • POST: add a new one.

• One for showing one item, editing it, deleting it. (/customers/:id/)

  • GET: customer details.

  • PUT: update customer info.

  • PATCH: partially update customer.

  • DELETE: delete customer.

You could use a generic single ModelViewSet, but Emad prefers having control of his URLs.

A tip: don’t go too deep with your hierarchy.

Another tip: version your API from the beginning. Prefix your URLs with /v1/, /v2/, for instance. This reduces breakage.

And: always return the coorect HTTP status codes. Look at https://httpstatuses.com/ . If you create a customer, return a 201 CREATED. If you request an unknown customer: 404 NOT FOUND.

(Note by Reinout: look at https://http.cat/, too :-) )

http://ccbv.co.uk/ is a great resource for django’s class based views. http://www.cdrf.co/ is the same for DRF.

Authentication:

• Don’t use http basic auth. You force the customer to send his password all the time. That is bad for an API.

• Django’s session authentication: use it only internally.

• It is much better to use TokenAuthentication (an external package).

• Also good: JWT (json web token) authentication. There’s a plug-in for django rest framework.

For permissions:

• User permissions: “is admin?”, “is authenticated?”.

• Regular model permissions.

• Object permissions: django-guardian is a third-party django app.

Handy: there is support for throttling:

• AnonRateThrottle for anonymous users.

• UserRateThrottle: throttling per authenticated user.

• ScopeRateThrottle for specific API scopes. You can set that per API endpoint.

When testing, use DRF test classes. APIRequestFactory, APIClient, APISimpleTestCase, etcetera. They’re specially made to make your tests easier.

For functional tests, you can use vcrpy to make mocking your web API much faster. You use it to give it a sort of test fixture instead of having it call the real API.

Another tip: use the ‘postman’ app to play with your API and to test it out in detail. He demoed the API: nice!