Prerequisites<\/h2>\n
To successfully complete the Django REST framework tutorial, you\u2019ll need the following:<\/p>\n
- \n
- PyCharm Professional<\/a> (a free 30-day trial is available). This tutorial has been created in PyCharm Professional 2023.2.1<\/strong><\/li>\n
- General understanding of the concept of RESTful APIs<\/li>\n
- Previous experience with Python and Django (you can start with our Django tutorial<\/a>)<\/li>\n<\/ul>\n
You can find the full code of the project in this repository<\/a>.<\/p>\n
Setting up a project<\/h2>\n
Click New Project<\/strong> on PyCharm\u2019s Welcome screen or select File | New Project<\/strong> from the main menu. When the New Project<\/strong> window opens, choose Django<\/strong> as the project type in the left-hand pane and do the following:<\/p>\n
- \n
- Specify the project directory, which will also be used as the project name (apiTutorial<\/kbd> in our example).<\/li>\n
- Choose the type of virtual environment for your project (we will use virtualenv<\/strong>).<\/li>\n
- Expand the More Settings<\/strong> section and provide the application name (rental<\/kbd>).<\/li>\n<\/ol>\n
You also need to disable the Enable Django admin<\/strong> checkbox. We will create the admin user manually later.<\/p>\n
\n![\"Creating](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/01_create_django_project-1.png\")
<\/figure>\n<\/div>\nWhen you click Create<\/strong>, PyCharm will set up the project and install Django in the project environment.<\/p>\n
The Django REST framework package needs to be installed manually. Open the Python Packages<\/strong> tool window by clicking its icon on the left. Search for the djangorestframework<\/kbd> package and install the latest version. In this tutorial, we\u2019ve used version 3.14.0.<\/p>\n
\n![\"Installing](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/02_install_drf_package-1.png\")
<\/figure>\n<\/div>\nNow we need to update
INSTALLED_APPS<\/code> in settings.py<\/strong>. Here\u2019s PyCharm\u2019s shortcut for that:<\/p>\n- \n
- Open Search Everywhere<\/strong> by pressing \u21e7 (Shift)<\/strong> twice.<\/li>\n
- Press Tab<\/strong> several times until you\u2019re on the Symbols<\/strong> tab.<\/li>\n
- Type the first letters of the desired symbol (variable, class, etc.) to find it, for example, \u201cinsapp<\/kbd>\u201d.<\/em><\/li>\n<\/ol>\n
\n![\"Opening](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/03_open_settings.png\")
<\/figure>\n<\/div>\n- \n
- Press Enter<\/strong> to jump to the desired symbol and add \u2018<\/em>
rest_framework<\/code>\u2019<\/em> toINSTALLED_APPS<\/code>.<\/li>\n<\/ol>\n\n![\"Adding](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/04_edit_settings.png\")
<\/figure>\n<\/div>\nCreating serializers<\/h2>\n
What are Django REST framework serializers?<\/h3>\n
In general, serializers are used to \u201ctranslate\u201d Django model instances or querysets into other formats, usually JSON or XML, so that they can be sent in the body of an HTTP response. Serializers also provide deserialization when text data from an HTTP request is parsed, validated, and converted into a model instance.<\/p>\n
The processes of serialization and deserialization are crucial for any API, and Django REST framework can take it over completely. Thanks to its
ModelSerializer<\/code> class, we can generate a serializer for any model in just two lines of code.<\/p>\nBut we still need to create a model. Let\u2019s do that.<\/p>\n
Writing a model-based serializer<\/h3>\n
Use Search Everywhere<\/strong> (double Shift) or the Project<\/strong> tool window (\u23181 \/ Alt+1<\/strong>) to open rental\/models.py<\/strong>, and copy the following code into the editor:<\/p>\n
from django.db import models\n\nSIZE_CHOICES = [\n ('ST', 'Studio'),\n ('1BR', '1 bedroom'),\n ('2BR', '2 bedrooms'),\n ('3BR', '3 bedrooms'),\n ('MBR', '3+ bedrooms'),\n]\nTYPE_CHOICES = [\n ('H', 'house'),\n ('APT', 'apartment'),\n]\n\n\nclass Offer(models.Model):\n created = models.DateTimeField(auto_now_add=True)\n address = models.CharField(max_length=100, blank=True, default='')\n size = models.CharField(choices=SIZE_CHOICES, default='1BR', max_length=100)\n type = models.CharField(choices=TYPE_CHOICES, default='APT', max_length=100)\n price = models.PositiveIntegerField(default=0)\n sharing = models.BooleanField(default=False)\n text = models.TextField(default='')\n\n class Meta:\n ordering = ['created']<\/pre>\nNote that all fields of the
Offer<\/code> model have defaults, which means that we can create an instance without providing any field values. Additionally, we\u2019ve provided choices<\/a> for thesize<\/code> andtype<\/code> fields.<\/p>\nNow let\u2019s run migrations. Open PyCharm\u2019s manage.py <\/strong>console by pressing \u2325R\/ Ctrl+Alt+R<\/strong> and type \u201cmakemigrations<\/kbd>\u201d followed by \u201cmigrate<\/kbd>\u201d.<\/em> Code completion is available, so you don\u2019t need to type out the whole commands.<\/p>\n
![\"Running](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/05_run_migrations.png\")
<\/figure>\nWe need to create serializers.py<\/strong> in the rental<\/strong> directory. Select the directory in the Project<\/strong> tool window (\u23181 \/ Alt+1<\/strong>), press \u2318N \/ Alt+Insert<\/strong>, select Python File<\/strong>, and specify \u201cserializers<\/kbd>\u201d<\/em> as the file name.<\/p>\n
\n![\"Creating](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/06_create_serializers.png\")
<\/figure>\n<\/div>\nThe newly created file opens in the editor. Fill it with the following code:<\/p>\n
from rest_framework import serializers\nfrom rental.models import Offer\n\n\nclass OfferSerializer(serializers.ModelSerializer):\n class Meta:\n model = Offer\n fields = ['id', 'address', 'size', 'type', 'price', 'sharing', 'text']<\/pre>\n
As you can see,
OfferSerializer<\/code> inherits from theModelSerializer<\/code> provided by Django REST framework and is defined with only two lines of code. On line 7 we\u2019ve specified the base model (which is imported from rental\/models <\/em><\/strong>on line 2), while line 8 contains the list of model fields to be serialized.<\/p>\nFor more information about Django REST framework serializers, see https:\/\/www.django-rest-framework.org\/api-guide\/serializers\/<\/a>.<\/p>\n
Using the serializer to save data<\/h3>\n
Let\u2019s use the newly created serializer to add data into the database. Open the Python console by clicking the corresponding icon on the left and run the following code in it:<\/p>\n
from rental.models import Offer\noffer = Offer(text='A cozy space in \"loft\" style.\\nPerfect for young couples')\noffer.save()\noffer = Offer(text='A warm house for a big family')\noffer.save()<\/pre>\n
\n![\"Creating](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/07_add_offer_manually.png\")
<\/figure>\n<\/div>\nWe\u2019ve created two instances of the
Offer<\/code> model and saved them into the database by using the built-insave()<\/code> method.<\/p>\nNow let\u2019s open the database. Your project contains db.sqlite3<\/strong>, which can be opened either from the Project<\/strong> tool window or by using Search Everywhere<\/strong>. When you open the database for the first time, PyCharm will register it as the project data source. The Data Sources and Drivers<\/strong> window will open.<\/p>\n
Click Test Connection. <\/strong>If you see a warning saying that you need to install, update, or switch the database driver, perform the required action. Then click OK<\/strong> to finish adding the data source to the project.<\/p>\n
\n![\"Adding](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/11_configure_database.png\")
<\/figure>\n<\/div>\nWhen the Database<\/strong> tool window opens, expand the structure of the db<\/strong> data source until you see the rental_offer<\/strong> table.<\/p>\n
\n![\"Exploring](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/111_explore_database.png\")
<\/figure>\n<\/div>\nClick it to browse its contents in the editor.<\/p>\n
![\"Exploring](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/12_view_table.png\")
<\/figure>\nAs you can see, there are two records in the database table now. We didn\u2019t provide values in any of the fields except
text<\/code>, which is why the default values from the model definition have been used.<\/p>\nProviding REST API logic<\/h2>\n
Writing function-based views<\/h3>\n
We\u2019ve successfully added two rental offers manually, but we want the API to be able to do that automatically based on the incoming requests. Let\u2019s start creating the API\u2019s logic in rental\/views.py<\/strong>. Open the file and fill it with the following code:<\/p>\n
from rest_framework import status\nfrom rest_framework.decorators import api_view\nfrom rest_framework.response import Response\nfrom rental.models import Offer\nfrom rental.serializers import OfferSerializer\n\n\n@api_view(['GET', 'POST'])\ndef offer_list(request):\n if request.method == 'GET':\n offers = Offer.objects.all()\n serializer = OfferSerializer(offers, many=True)\n return Response(serializer.data)\n\n elif request.method == 'POST':\n serializer = OfferSerializer(data=request.data)\n if serializer.is_valid():\n serializer.save()\n return Response(serializer.data, status=status.HTTP_201_CREATED)\n return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)<\/pre>\n
We\u2019ve added a function-based view called
offer_list<\/code>. It will be used to provide information about available rental offers, as well as to add new offers to the database. Here\u2019s what\u2019s inside:<\/p>\n- \n
@api_view<\/code> (line 8) <\/em>is the Django REST framework decorator for function-based views.GET<\/code> andPOST<\/code> are the methods accepted by this view.<\/li>\n- If the request method is
GET<\/code>, a queryset with all offers in the database is created (line 11) and serialized (line 12). In this case, the body of the response contains data about all available offers in JSON form. The response is sent with the default status code (200 OK<\/code>).<\/li>\n- If the request method is
POST<\/code>,OfferSerializer<\/code> is used to deserialize data from the request (line 16). If the data is validated successfully (line 17), it\u2019s saved to the database (line 18). The response contains the saved data and has the status code201 Created <\/code>(line 19).<\/li>\n- If validation fails, the API will return the error info with the status
400 Bad Request.<\/code><\/li>\n<\/ul>\nIt would also be useful if we could obtain information about any specific offer, edit that information, and remove offers from the database. Let\u2019s add another view and call it
offer_detail<\/code>:<\/p>\n@api_view(['GET', 'PUT', 'DELETE'])\ndef offer_detail(request, pk):\n try:\n offer = Offer.objects.get(pk=pk)\n except Offer.DoesNotExist:\n return Response(status=status.HTTP_404_NOT_FOUND)\n\n if request.method == 'GET':\n serializer = OfferSerializer(offer)\n return Response(serializer.data)\n\n elif request.method == 'PUT':\n serializer = OfferSerializer(offer, data=request.data)\n if serializer.is_valid():\n serializer.save()\n return Response(serializer.data)\n return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)\n\n elif request.method == 'DELETE':\n offer.delete()\n return Response(status=status.HTTP_204_NO_CONTENT)<\/pre>\n
This view accepts three methods (
GET<\/code>,PUT<\/code>, andDELETE<\/code>) and works as follows:<\/p>\n- \n
- First of all, it checks whether the offer whose ID has been specified in the
pk<\/code> parameter exists in the database (line 4). If it doesn\u2019t,404 Not Found<\/code> is returned.<\/li>\n- For
GET<\/code> requests, the API serializes the offer data (line 9) and returns it in the response body.<\/li>\n- For
PUT<\/code> requests, the API serializes the offer data from the database and merges it with the data from the request body (line 13). If the validation is successful (line 14), the updated offer is saved to the database (line 15) and returned in the response body (line 16). Otherwise, the error info is returned with the400 Bad Request status<\/code>.<\/li>\n- Finally, for
DELETE<\/code> requests, the API deletes the offer and returns204 No Content.<\/code><\/li>\n<\/ul>\nNow that we\u2019ve defined the API\u2019s logic, we have only one step left before we can use our API. We need to define Django URLs, also known as API endpoints.<\/p>\n
Defining and testing API endpoints<\/h3>\n
Let\u2019s start by creating urls.py<\/strong> in the app directory and filling it with the following code:<\/p>\n
from django.urls import path\nfrom rental import views\n\nurlpatterns = [\n path('offers\/', views.offer_list),\n path('offers\/<int:pk>\/', views.offer_detail),\n]<\/pre>\nWe\u2019ve defined two endpoints for our two views. Don\u2019t forget to include rental\/urls.py<\/strong> in the project\u2019s urls.py<\/strong> file:<\/p>\n
from django.urls import path,include\n\nurlpatterns = [\n path('', include('rental.urls')),\n]<\/pre>\nLet\u2019s open the Endpoints<\/strong> tool window. In case you haven\u2019t used it before, you can find it under the meatball menu on the left.<\/p>\n
\n![\"Opening](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/13_open_endpoints.png\")
<\/figure>\n<\/div>\nThe tool window displays all available endpoints and methods.<\/p>\n
\n![\"Endpoints](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/14_explore_endpoints.png\")
<\/figure>\n<\/div>\nBefore testing the API, make sure that the Django server is running. On project creation, PyCharm automatically set up the run configuration. Just launch it from the Run<\/strong> widget in the window header. Note the server address (usually, localhost<\/em>) and port number in the Run<\/strong> tool window that opens.<\/p>\n
\n![\"Launching](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/15_launch_django_server.png\")
<\/figure>\n<\/div>\nLet\u2019s go back to the Endpoints<\/strong> tool window. Select offers\/GET<\/strong> in the list and switch to the HTTP Client<\/strong> tab at the bottom. Edit the port number if needed and then click Submit Request<\/strong>.<\/p>\n
\n![\"Submitting](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/16_submit_get_request.png\")
<\/figure>\n<\/div>\nPyCharm runs the request and saves the response body to a file. You can either scroll up to explore the response or click the link to open the file in the editor.<\/p>\n
\n![\"Response](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/17_explore_response.png\")
<\/figure>\n<\/div>\nLet\u2019s submit a
DELETE<\/code> request to remove the second offer (DELETE http:\/\/localhost:8000\/offers\/2\/<\/a><\/code>) and then submit another request for the list of available offers. Now only one offer is available.<\/p>\n\n![\"List](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/18_delete_and_get_again.png\")
<\/figure>\n<\/div>\nAnother amazing feature of Django REST framework is its browsable API<\/a>. Opening http:\/\/127.0.0.1:8000\/offers\/<\/a> in your browser brings you to a page where you can view the list of available offers and add new ones.<\/p>\n
- For
- If the request method is
- Press Tab<\/strong> several times until you\u2019re on the Symbols<\/strong> tab.<\/li>\n
- Choose the type of virtual environment for your project (we will use virtualenv<\/strong>).<\/li>\n
![\"Using](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/19_browsable_api.png\")
<\/figure>\n<\/div>\n![\"Submitting](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/20_submit_post_request.png\")
<\/figure>\n<\/div>\n![\"Errors](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/21_bad_request_status.png\")
<\/figure>\n<\/div>\n![\"Successful](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2023\/09\/22_successful_post.png\")
<\/figure>\n<\/div>\n