DEV Community: Conrad

Django REST Framework for Beginners: How to Create Your First API

Conrad — Tue, 16 Jan 2024 07:37:36 +0000

As a developer, beginner or seasoned, I am sure you have come across the word api or REST api before. So what does it mean? API stands for Applicatin Programming Interface and is a set of rules and instructions that allow different software components to communicate with one another. APIs make it easier of developers to create services and applications by using existing features or data from other platforms or applications. For example you can create a weather app by using data from weather forecasting companies, saving time from having to gather the data yourself.

REST API or RESTful API is an API that follows a set architectural contstraints for creating web services. REST APIs use HTTP requests to perform standard database functions such as creating, reading, updating and deleting. For more details, I suggest reading this article .
Now that we have some understanding on APIs, let's build a simple API using django REST framework.

Django REST framework is a popular and powerful library for creating web APIs in Python. It provides a range of features and tools that make it easy to build, test, and document RESTful services. In this article, we will learn how to use Django REST framework to create a simple API with CRUD functionality. We will cover the following topics:

How to install Django REST framework
How to create models, serializers, and views.
How to use URL patterns to define our API endpoints
How to test our API

By the end of this article, you will have some understanding of how to use the Django REST framework to build your own web APIs. Let’s get started!

Setup

As we are using python and django, ensure you have django installed on your system. Install the django rest framework by running the command ‘pip install djangorestframework’. Add the django rest framework into your installed apps list in your setting.py file. Create a new django app which will be used to build the api and add it to the installed apps list. For the sake of this project, name the new app api.

INSTALLED_APPS = [
    ...
    'rest_framework',
    'api',
]

Serializers and models

Serializers are a very important part of Django REST framework , they handle convertion between complex data types such as model instances and primitive values such as JSON or other content types. They are also responsible for deserialization and check the input data for errors and convert it back to complex types.
To create serializers, start by creating a new file called ‘serializers.py’ inside the api app folder. Before you start working with serializers, ensure you create your models and make necessary migrations. Here is the model used for this project

from django.db import models
import uuid
# Create your models here.
class Posts(models.Model):
    id = models.UUIDField(primary_key=True,default=uuid.uuid4,editable=False,unique = True)
    post_name = models.CharField(max_length = 150,blank=False,null=True)
    post_user = models.CharField(max_length=50,blank=False,null=True)
    created = models.DateTimeField(auto_now_add=True,blank=False,null=True)


    def __str__(self):
        return self.post_user

You can choose to use custom id like in the case above, if not, you can skip that line of code entirely. If all this is new to you I suggest reading about django

Now in the serializers.py file, import the serializers module from rest_framework and all the models you want to work with.

from rest_framework import serializers
from .models import Posts

Now create a new serializer class as shown below:

class PostsSerializer(serializers.ModelSerializer):
    class Meta:
        model = Posts
        fields ='__all__'

PostsSerializers is the name of of the serializer class.
model=Posts tells the class what model it will serialize.
fields='__all__' tells the serializer which fields of the model will be serialized.

If you want to serialize more that one model, ensure you create a serializer class for each model.

Views and urls

Inside your main project folder, open the urls.py file and include the urls for the api app.

from django.contrib import admin
from django.urls import path, include
urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/',include('api.urls')),
]

Inside your api app folder create a urls.py file and add url patterns. You can add just one path for testing purposes.

from . import views
from django.urls import path

urlpatterns = [
    path('',views.index,name='index'),
]

Within the api app folder, open the views.py file. This is where the api logic will be written on. There are several imports needed:

from .models import Posts
from .serializers import PostsSerializer
from rest_framework.decorators import api_view
from rest_framework.response import Response

from .models import Posts : imports the model Posts created in the models.py file
from .serializers import PostsSerializer : imports the PostsSerializer created in the serializers.py file. It will be used to convert instances of the model Posts into a format that can be easily rendered in JSON format.
from rest_framework.decorators import api_view : imports the api_view decorator from the django rest framework. This decorator is used to define views for handling different HTTP requests such as GET , POST and others.
from rest_framework.response import Response : imports the response class which is used to create HTTP responses in views.

Now create a view for the api:

@api_view(['GET'])
def index(request):
   urls = {
        'All Posts':'posts',
        'View single post':'post/<uuid:id>',
        'Create post':'create-post',
        'Delete post':'delete-post/<uuid:id>',
        'Edit post':'edit-post/<uuid:id>',
    }
    return Response(urls)

There are 2 main differences between this view and ordinary django view which are @api_view(['GET']) and the return Response(urls).

@api_view(['GET']) : This decorator specifies the index view to only respond to HTTP GET requests
Response(urls) : Creates a HTTP response with a JSON payload of the data urls.

Test the api by running the server and navigating to http://127.0.0.1:8000/api/. If done correctly you should see the following page

Congrats! You have an api up and running! Now let's add CRUD functionality to the api. CRUD stands for create, read, update, delete.

Before that, we want the api to be able to list all data in the model Posts, for that do the following:

@api_view(['GET'])
def listPosts(request):
    posts = Posts.objects.all()
    list = PostsSerializer(posts,many=True)
    return Response(list.data)

@api_view(['GET']): this decorator specifies the view listPosts will only accept HTTP GET requests
posts = Posts.objects.all(): Retrieves all posts from the database
list = PostsSerializer(posts,many=True): Creates an instance of the PostsSerializer class, which is responsible for converting multiple instances of posts( all data retrieved from the model Posts).
return Response(list.data): Generates a HTTP response using the Response class from django rest framework. The serializer.data contains the serialized data of the model. This response is in JSON format which is common in most APIs.

Create a url path in the urls.py file inside the api app folder.

path('posts/',views.listPosts,name='posts'),

Then navigate to http://127.0.0.1:8000/api/posts and you should see the following page.

You can add some data through the django admin panel, which will display on this page.

CRUD Functionality

Create

For the API to accept data input, there are a few changes that need to be made

@api_view(['POST'])
def makePost(request):
    serializer = PostsSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save()

    return Response(serializer.data)

@api_view(['POST'] : This decorator specifies the view makePost should only accept HTTP Post requests.
serializer = PostsSerializer(data=request.data) : Creates an instance of the PostsSerializer class. The serializer converts the request data into a Python dictionary that can be used to create or update a Post model instance.
if serializer.is_valid():serializer.save() : This checks whether the data provided in the request is valid according to the rules defined in the serializer. If the data is valid, this line saves the data to the database using the serializer.
return Response(serializer.data) : returns a Response object that contains the serializer’s data as the body.

Create a new url path in your urls.py file inside your api app folder.
path('create-post/',views.makePost,name='create-post'),

Navigate to this url and you should see something similar to this

You can add data on content input. The data you add should be in JSON format, for example
{ "id": "04c62826-14ee-489c-ba5e-56dc98d8d2a7", "post_name": "Home is 127.0.0.1", "post_user": "X53Tq0Ui", "created": "2024-01-11T11:55:41.126952+03:00" }
Change the properties which are, id, post_name to match the fields your model has. Once complete, submit the form.

After submitting the data, you should see the following:

Also on the posts list you should be able to see it

Read

Reading is simply viewing a specific post. It is done by passing the id of the post you want to view and it will be retrieved and a response will be rendered.

@api_view(['GET'])
def postDetails(request,id):
    post = Posts.objects.get(id=id)
    serializer = PostsSerializer(post,many=False)
    return Response(serializer.data)

@api_view(['GET']) : This decorator specifies the view makePost should only accept HTTP Post requests.
post = Posts.objects.get(id=id) : Retrieves a specific post from the database.
serializer=PostsSerializer(post,many=False) : Creates a serializer instance for a single instance of the Posts model.
return Response(serializer.data) : Returns a Response object that contains the serializer’s data as the body.

Create url path for this view inside the urls.py file in the api app folder path('post/<uuid:id>/',views.postDetails,name='post'),, then navigate to the link http://127.0.0.1:8000/api/post/(add the id here without brackets). You should see the following

Update

For update, you pass in the id of the object that you want to update. The api will respond with the object which can be edited as needed and submitted. Let's do it practically.

@api_view(['POST'])
def editPost(request,id):
    post = Posts.objects.get(id=id)
    serializer = PostsSerializer(instance=post,data=request.data)
    if serializer.is_valid():
        serializer.save()

    return Response(serializer.data)

post = Posts.objects.get(id=id) : Retrieves the specific object from the database.
serializer = PostsSerializer(instance=post,data=request.data) : This is using the PostsSerializer to update the existing post with the new data prodived from request.data.

The rest of the code checks whether the data is valid and returns a JSON response of the new data.

Create another url route in the urls.py file inside the api app folder.
path('edit-post/<uuid:id>/',views.editPost,name='edit-post'),

To test it, copy the id of an object you want to update and paste it to the url, example http://127.0.0.1:8000/api/edit-post/c34fcfe4-dc69-4080-ace3-bcc0c02b79ef/. It should open a new page similar to create post page where you can input a JSON data. Once you submit, it will replace the existing data with the new data.

Delete

Just like read and update, pass the id of the object to the api view through the url, then the object will be retrieved from the database then finally it will be deleted. The HTTP request used in this case is DELETE. Let's see it in action

@api_view(['DELETE'])
def deletePost(request,id):
    post = Posts.objects.get(id=id)
    post.delete()
    return Response('Post Deleted!')

@api_view(['DELETE']) : This decorator specifies that the deletePost view should only respond to HTTP DELETE requests.
post = Posts.objects.get(id=id) : Retrieves the Post instance with the given id from the database.
post.delete() : If the Post instance is found, it is deleted from the database using the delete() method.
return Response('Post Deleted!') : After successful deletion, the view returns a response indicating that the post has been deleted.

After successful deletion

Conclusion

And there you have it, a REST API with full CRUD functionality.You can read more on django rest framework from their site here. From here on, I recommend building a similar api on your own to solidify your understanding. You can research on how to add more features such as file upload, user registration and login. You can also build a to do list api and connect it to the frontend using frontend frameworks such as React, Vue or just use plain JavaScript. The possibilities are endless, it your job to research and build bigger, better and more secure APIs. Happy coding!

Mastering File Uploads in Django: A Comprehensive Guide.

Conrad — Mon, 21 Aug 2023 16:30:00 +0000

INTRODUCTION

File upload is a very important feature in web and mobile app development. It allows us to upload images for our online profile pictures, share funny videos with friends, send emails with school assignments, upload music and much more.
When it comes to building web applications using Django, a Python web framework, handling file uploads becomes not only feasible but also streamlined. Whether you're creating a platform for sharing images, documents, or any other type of file, understanding the inner working of file uploads in Django is essential.
In this comprehensive guide, we will walk through the process step by step and by the end, you'll have the knowledge and confidence to seamlessly integrate file upload functionality into your Django projects, enriching user experiences and expanding the capabilities of your web applications.

File Upload in Django: The Steps

Assuming you have already created you django project and linked your app to your main project:

Configure media settings: In the settings.py file in your project create media root and media url

MEDIA_URL = '/uploads/'
MEDIA_ROOT = os.path.join(BASE_DIR,'static')

Update URLs confugirations: In your urls.py file add the following line of code

from django.urls import path
from . import views
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    .
    .
    .
]+ static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Create file upload model: Design a model to manage uploaded files. For example a model for uploading profile pictures.

from django.db import models

class ProfilePics(models.Model):
    name = models.CharField(max_length=20)
    nickname = models.CharField(max_length=20)
    image = models.FileField(upload_to='profile')
    uploaded_at = models.DateTimeField(auto_now_add=True)

Prepare Storage Directory: Inside your static folder, ensure you have another folder called 'profile' where the image will be uploaded to.

Upload Form Setup: Create a form for file upload.Ensure you include all necessary fields.

from django import forms
from .models import ProfilePics
class ProfilePicsForm(forms.ModelForm):
    class Meta:
        model = ProfilePics
        fields = ('name', 'nickname','image')

Upload View Setup: Finally create a view to handle the file upload using the form. In the templates folder, ensure your have created the html template where the form will be rendered to.

from django.shortcuts import render, redirect
from .forms import ProfilePicForm

def upload_file(request):
    if request.method == 'POST':
        form = ProfilePicsForm(request.POST, request.FILES)
        if form.is_valid():
            form.save()
            return redirect('uploaded_files')  # Redirect to a view showing uploaded file(s)
    else:
        form = ProfilePicsForm()
    return render(request, 'upload-pic.html', {'form': form})

Testing: Now run the server and test the functionality.

Some Explanation

MEDIA_URL specifies the url that will be used to serve your uploaded media files. When you want to display or access uploaded files, you'll prepend this URL to the file's path. For instance, if you have an uploaded image at media/images/my_image.jpg, and MEDIA_URL is set to '/images/', you can reference the image's URL as { MEDIA_URL }my_image.jpg.
MEDIA_ROOT is the absolute filesystem path to the directory where uploaded media files are stored. In this case, you're setting it to a directory named static at the root of your project (BASE_DIR).
upload_to='profile' this line simply means that the file will be uploaded into the folder called profile within your main static folder.

Note: It is important to understand that when uploading a file, what is saved to the database is not the actual file itself but the path to the file.

CONCLUSION

Understanding the art of file uploads in Django opens up a world of possibilities for creating dynamic and interactive web applications. Through the correct integration of models, forms, and views, Django streamlines the process of handling file uploads and storage. By carefully configuring settings for static and media files, and leveraging the power of the FileField and ImageField fields, developers can seamlessly facilitate the uploading and presentation of various file types, be it images, PDFs, documents, or more.

It is important to note that this article provides a basic understanding of file uploads in Django, and there is plenty of room for customization and further research and exploration.
Remember, while you are integrating file upload feature or any other feature django has to offer, stick to Django's rules and keep up with the latest advancements to ensure that you create applications that deliver a polished, engaging user experience. Happy coding!

Image by Tumisu from Pixabay

Unleashing the Power of Elegance: A Guide to Styling Django Forms

Conrad — Sat, 05 Aug 2023 15:26:09 +0000

Introduction
In web development, Django forms come in handy in speeding up development and making the data collection process much simpler. They however lack the visually appealing look and feel we desire. So, how do we style them? In this article, we shall explore 2 effective ways of styling Django forms and make them visually appealing and leave a lasting impression on your users.

Styling Django Forms: The Two Approaches

1. Django crispy-forms

This is a popular third-party Django app that improves the rendering and styling of Django forms. It is built on top of Django’s built in Django forms framework and makes it easy to control the way forms are represented in the website. With Crispy Forms, you can quickly specify how your forms should be rendered on the frontend, making the process of styling and customizing the form layouts easier and more standardized. You can learn more about Django crispy forms from their official documentation here.

To use crispy forms, we must first install it to our local machine using the command: pip install django-crispy-forms
After a successful install, add it to the installed apps list in your Django application

INSTALLED_APPS = [
    .
    .
    .
    'crispy_forms',
]

On your html template that contains the django form, add the load crispy for tags at the top of your page.

{% load crispy_forms_tags %}

Finally add the ‘|crispy’ filter to your form content as shown:

<form action="" method="post">  
    {{form|crispy}}
    <input type="submit"/>
</form>

Now refresh your page and see the results. For more in-depth information and advanced usage of Django Crispy Forms, refer to their official documentation.

2. Manual Styling

Manual styling involves assigning custom classes or id attributes to individual form fields, similar to traditional HTML forms. By doing so, you gain complete control over the form's appearance and behavior, enabling you to tailor it to their specific design preferences. This method proves particularly advantageous when seeking to achieve a fully customized and unique styling for Django forms, as it allows for seamless integration with CSS, empowering the creation of visually stunning and user-centric web interfaces. Let’s now see how it’s done.

Create a new file ‘forms.py’ in your apps root folder

In the forms.py file, import forms and other necessary modules.

from django import forms

Start by creating a form using the default Django form creation method.

class UserRegister(UserCreationForm):
    class Meta:
        model = User
        fields = ['username','email','password1','password2']

Now customize the fields as desired.

username = forms.CharField(widget=forms.TextInput(attrs={'class': 'form-control','placeholder':'Your username'}))

 email = forms.EmailField(widget=forms.EmailInput(attrs={'class':'form-control','placeholder':'Your email Eg: sample@sample.com'}))

password1 = forms.CharField(widget=forms.PasswordInput(attrs={'class':'form-control','id':'pass-one','placeholder':'Enter password'}))

 password2 = forms.CharField(widget=forms.PasswordInput(attrs={'class':'form-control','id':'pass-two','placeholder':'Repeat password'}))

Some explanation:

username=forms.CharField(widget=forms.TextInput(attrs={'class':'form-control','placeholder':'Your username'})): By changing the 'username' field's widget to a TextInput and adding some HTML attributes using the attrs dictionary, this line personalizes the field. In this instance, the field will be displayed as a text input with the placeholder text "Your username" and the class "form-control," which is frequently used in Bootstrap-based projects.
email=forms.EmailField(widget=forms.EmailInput(attrs={'class':'form-control','placeholder':'Your email Eg: sample@sample.com'})): The 'email' field is modified by this line, which changes the widget to an EmailInput and adds HTML attributes by using the attrs dictionary. The field's placeholder text will read, "Your email Eg: sample@sample.com," and the field will be shown as an email input with the class "form-control."
password1=forms.CharField(widget=forms.PasswordInput(attrs={'class':'form-control','id':'pass-one','placeholder':'Enter password'})): This line alters the 'password1' field by changing its widget to a PasswordInput and adding HTML attributes using the attrs dictionary. The field will display as a password input with the class "form-control," an id of "pass-one," and the default text "Enter password."
password2=forms.CharField(widget=forms.PasswordInput(attrs={'class':'form-control','id':'pass-two','placeholder':'Repeat password'})): This line alters the 'password2' field, similar to the 'password1' field, but with a different id attribute ('pass-two') and a placeholder text 'Repeat password'.

Now with these adjustments, the UserRegister form will display with the desired styles and placeholder texts for each field, making the user registration process more aesthetically pleasing and user-friendly.

Conclusion

Using these 2 methods guarantees your Django forms will be visually appealing and will certainly leave a lasting impression on your users. Remember to keep user experience at the forefront of your design choices. A user centric interface will not only enhance the overall usability of your application but also pave the way for increased user satisfaction and loyalty.

Understanding *args & **kwargs

Conrad — Tue, 21 Mar 2023 16:32:57 +0000

If you have ever needed to pass a variable number of arguments to a Python function you may have come across the *args and **kwargs syntax. These powerful tools allow you to pass a variable number of non-keyword and keyword arguments, respectively. In this post, lets dive into what *args and **kwargs are, how they work, and provide some examples to help you better understand these Python features.

What is *args?
It is a special syntax used in python function definition to pass a variable/unlimited number of non-keyword arguments to the function. Let’s use an example to make things more clear.

Example 1: Create a python function that takes in any number of values and sum all values passed to it.

def add(*args):
    sum = 0
    for arg in args:
        sum += arg
    print(f"The sum is: {sum}")

add(1,2,3,4,5,6,7,8,9)

Output: The sum is: 45

Example 2: Create a python function to display all car brand names passed to it.

def names(*args):
    print("The car brands are:")
    for arg in args:
        print(arg)

names('Jeep','Volkswagen','Toyota','Ford','Rivian','Tesla')

Output:
The car brands are:
Jeep
Volkswagen
Toyota
Ford
Rivian
Tesla

What is **kwargs?
It is a special syntax used to pass keyword arguments to a function. These keyword arguments can be of any number just like in args. A keyword argument is where you give a name to the argument as you pass it to the function. Let’s use some examples to make things clear.

Example 1:

def names(**kwargs):
    for key, value in kwargs.items():
        print(f"{key}: {value}")

names(Fname="John",Lname="Doe",work="Doctor")

Output:
Fname: John
Lname: Doe
work: Doctor

It is important to note that args and kwargs are just names and can be replaced with whatever names you like. What is important is the * and ** operators which are called unpacking operators. These operators must be included whenever you want to create such functions. To prove this, lets rename args and kwargs in the above examples.

Example 1:

def names(*cars):
    print("The car brands are:")
    for x in cars:
        print(x)

names('Jeep','Volkswagen','Toyota','Ford','Rivian','Tesla')

Output:
The car brands are:
Jeep
Volkswagen
Toyota
Ford
Rivian
Tesla

Example 2:

def names(**names):
    for key, value in names.items():
        print(f"{key}: {value}")

names(Fname="John",Lname="Doe",work="Doctor")

Output:
Fname: John
Lname: Doe
work: Doctor

Why use *args and **kwargs.
These two python features are very useful in creating functions which the number of arguments to be provided is not known.

Conclusion

*args passes a variable number of non-keyword arguments.
**kwargs passes a variable number of keyword arguments.
Keyword arguments are arguments that have a key and value. For example, fname=”name”
The names args and kwargs can be changed to whatever you want, the most important part are the unpacking operators * and **.