Django REST Framework
10 min read
Not knowing much about how Django works, but needing to use it for professional reasons, I decided to sign up for a beginners course on the Django REST Framework. I recently completed it and thought I'd share my notes, which serves as a starter guide for anyone wanting to set up a Django project (with the primary purpose of serving a REST API). The corresponding repo can be found on my GitHub.
What I didn't initially appreciate, was that the Django REST Framework is an add-on package to the base Django framework. It needs to be installed separately, but once installed, allows for the creation of REST API endpoints in a more efficient way.
How the repo works
- Uses Vagrant to create a containerised application, which is run inside a Virtual Machine (I use Virtual Box on my MacBook Pro). Ensure you have installed this and enabled your MacBook to use Oracle’s Virtual Box in the Securities & Preferences settings.
- To start Vagrant:
- Ensure you have a virtual environment set up in Vagrant. To do this, run
cd /vagrant, and
python -m venv ~/env.
- Activate the virtual environment:
- Install the requirements:
pip install -r requirements.txt.
To set up a new project
- Ensure you've got your virtual environment set up and activated.
- Create your
requirements.txtfile with the same packages as what's in the repo, then...
One time setup of Django project
django-admin startproject profiles_project .
settings.py, add ‘rest_framework’ and ‘rest_framework.authtoken’ to the INSTALLED_APPS list.
Creating new apps
- Create the first app within the
python manage.py startapp profiles_api.
settings.py, add ‘profiles_api’ to the INSTALLED_APPS list.
Start Django web development server
python manage.py runserver 0.0.0.0:8000. If there’s an infinite loop situation, try
python manage.py runserver 0.0.0.0:8000 --noreload
- Navigate browser to http://localhost:8000/
- Models are used by us to describe the data needed for our project.
- Django sets up the database using these models.
- Each model maps to a specific table in the database.
- Django manages the relationship between our models and database, so we don’t need to interact with database directly.
- Docs: https://docs.djangoproject.com/en/3.2/topics/db/models/
- NOTE: The User model is provided to us out of the box by Django. We can override this in the
models.pyfile within the
- Django creates migration files to ensure our database matches our models.
- In our vagrant directory and virtual environment, run
python manage.py makemigrations profiles_api. This generates the migration file in the
migrationsfolder of the app in question.
python manage.py migrateto apply the migration file to the database. This goes through our entire project and runs all migration files.
Using the Django admin dashboard
admin.py, import the model(s) from the various apps.
- Dashboard is accessible at http://localhost:8000/admin/
- Auth Token comes from the Django REST framework. Authentication and authorization comes from Django out of the box.
- User profiles is automatically deduced from the way we named our UserProfile. It also pluralises it.
Django REST Framework
- Offers some helper methods to help us create our API endpoints.
- The Django REST framework Views provided are the APIView and ViewSet classes.
- Most basic type of view to build our API. Is similar to a traditional Django View but specifically for APIs.
- Describes the logic that makes up an API endpoint. Gives us the most control over our application logic.
- Allows us to match standard HTTP methods: GET, POST, PUT, DELETE.
- Might be better to use this when:
- Need full control over the logic (e.g. multiple data sources).
- Processing files and rendering a synchronous response.
- Call other APIs / services in the same response.
- Accessing local files or data.
- Create an APIView:
profiles_api/views.py. Create class based on APIView class.
- Define HTTP methods to handle. Each method must return a
Responseobject takes in either a list or dictionary (to allow it to convert to JSON).
- Define a URL endpoint and assign it to this new view.
- To define a URL endpoint:
- In our
profiles_apiapp, create a
urls.py, be sure to import
django.urls. This allows us to include other app URLs into our root.
- Add a URL to the list.
- In our
- Provided by Django REST framework. Allows us to easily convert data inputs into Python objects and vice versa.
- In our
profiles_apiapp, create a
- Our serializers should specify the fields we want to accept from the client. Similar to Django forms. They also take care of validation rules that are required for the fields.
- Hook this up to our APIView in
- Check it works by going to http://localhost:8000/api/hello-view/ and testing it out through the browsable API.
- Like APIViews, ViewSets allow us to write logic for endpoints. Instead of writing functions that map to common HTTP methods, it accept functions that map to common API object actions e.g. list (objects), create, retrieve, update and destroy [an object].
- Perfect for standard database operations. Fastest way to make a database interface.
- Cases of when to use ViewSets over APIView:
- A simple CRUD API on existing database model.
- A quick and simple API for pre-defined objects.
- Little to no customisation on the logic.
- Working with standard data structures.
- Create a ViewSet by:
views.py, create a class based on ViewSet.
- Define the action methods.
- Define the URL endpoint in
urls.pyand register our ViewSet through a router (provided by REST framework). Once then, add this to the urlpatterns (one time requirement).
- Check it works by going to the root of our API http://localhost:8000/api . You should be able to see the new URL we defined in the router. Note, this feature doesn’t show APIView URLs.
- When defining the create method, we can use the same serializer concept as in the APIViews.
Creating the profiles API
- In the
serializers.pyfile, create a
UserProfileSerializerwhich inherits a
ModelSerializer. Define the
Metaclass which is used to specify:
- What the relevant model is.
- The fields to include.
- Extra settings e.g. to make the password write only and to style the field in the browsable API.
- In this case, we want to overwrite the
createmethod to ensure the password input is saved as a hash. We also need to add an
updatemethod to handle the password hashing properly.
- Next, create a viewset through
viewsets.ModelViewset. Designed to manage models through the API. Provide a queryset so it knows which objects will be managed.
- Django REST framework knows the standard functions we need like create, list, destroy and update. We just need to assign the
queryseton which to perform these functions.
urls.py, register a new URL. We don’t need to add a
base_namebecause we defined a queryset in the viewset. This therefore allows it to default to the model in question. We can add a
base_nameif we want to override this.
Test it works
python manage.py runserver 0.0.0.0:8000and go to http://localhost:8000/api/profile/
- We can now create a new user in the HTML form. Going to http://localhost:8000/api/profile/1/ also allows us to see and update the details for an individual user.
- Create a new file called
permissions.pyto create a custom permission class. This will inherit from
BasePermissionwhich provides the
- SafeMethods are ones that don’t make any changes to the object like GET. We want users to view other users’ profiles, but only be able to change their profile. We do this by checking if the object ID they are trying to change matches the
user_idmaking the request.
- Next, open
views.pyfile and import TokenAuthentication. This utilises a random string that’s appended to each request from the user.
authentication_classes = (TokenAuthentication,)to the
UserProfileViewSetclass. Add a comma, to ensure it’s added as a tuple. Note that you can add more than one authentication class if you wish.
- Authentication classes sets method of authentication. Permission class sets the permission level. Add
permission_classes = (permissions.UpdateOwnProfile,)which is the custom permissions class we just created.
- Test in the browser by going to http://localhost:8000/api/profile. We will be able to see all users’ profiles since GET is a safe method. If we go to http://localhost:8000/api/profile/1/ we will no longer be able to see the forms to update the user.
- In the
filter_backends = (filters.SearchFilter,)to the
- Also define the searchable fields.
- Test in the browser by clicking on the new “filters” button. In effect, this adds a search param to the GET url. e.g. http://localhost:8000/api/profile/?search=test
Add login API
- In the
from rest_framework.authtoken.views import ObtainAuthTokento import the
- Add a new class called
UserLoginApiViewwhich inherits from
ObtainAuthToken. Whilst we can add this directly to our URLs, it won’t allow us to see this in our browsable API, so we need to override this and create our custom class.
- Do this by adding
renderer_classes. Note that the ModelViewset comes with this as default.
- Go to
urls.pyand define a ‘login/’ url with our new
- Test in the browser by going to http://localhost:8000/api/login/. You should be able to see the token in the response when you submit your username and password. Make a note of the token.
- Use the ModHeader Chrome extension to add the token to the request header. (Authorization: Token).
Create profile feed API
- Create a new model called
ProfileFeedItem. Each item will be linked to a
user_profile, so we need to set this as a
on_delete=models.CASCADEmeans that when a user is deleted, all of their other ProfileFeedItems will be deleted as well. Alternatively, we can set to null.
- Need to run migration to create the table. Run
python manage.py makemigrationsand
python manage.py migrate.
Add to admin dashboard
ProfileFeedItemSerializerwhich inherits from
- Add all the fields from
ProfileFeedItem, and make the
user_profilefield to read only.
- Create a new viewset called
- Provide a
querysetwhich is the
- Because we only want the authenticated user to be able to create an item, we need to add
perform_createto override the create method.
- Add a new URL called ‘feed’ to our
- Test it in the browser sending the authenticated user token. You should be able to POST, UPDATE and DELETE.
Create custom permission class
- To ensure a user can only update their own ProfileFeedItem, we need to define a new permissions class called
UpdateOwnStatus. Do this in
- In the viewset, set
permission_classes = (permissions.UpdateOwnStatus, IsAuthenticatedOrReadOnly). This means that a user must be authenticated, otherwise it’s readonly. The can also only update an item that they own.
Ensure only authenticated users can view the feed
- Instead of using
IsAuthenticatedin the viewset.