Use Django REST Framework and Managed Postgres to Build an API
19 minToday we will build an API with Django REST framework. For this project, we will build a URL shortener.
A URL shortener is a service that transforms long and complex URLs into short, easily memorable ones. This tutorial guides you through creating a URL shortener using Django REST framework and Postgres, deploying it on Koyeb.
Learn to generate short URLs, replace links, and track access counts. This tracking feature is valuable for assessing the performance of marketing campaigns.
By the end, you'll have the skills to develop your URL shortening service, similar to popular platforms like bit.ly or tinyurl.com, and take it live using Koyeb's platform. Whether you're a Django enthusiast or just looking to build a practical web service, this tutorial will provide you with the steps and insight to kickstart your project.
Want to see the final product in action? You can deploy and preview the URL Shortener application from this guide using the Deploy to Koyeb button below:
Note: Make sure to replace the DATABASE_URL
with your value and ?sslmode=require
added at the end.
Requirements
Before we dive into building our URL shortener with Django REST and Postgres, ensure that you have all the necessary tools and software in place. Here are the requirements for this project:
- Python version 3.8 or higher installed on your system.
- A Koyeb account to deploy your URL shortener
- A GitHub account to store your Django project code and trigger deployments
Steps
To successfully develop this application and deploy it to production, you will need to follow these steps:
- Create a Python Virtual Environment
- Install Django and Django REST Framework
- Create a Django Project
- Set Up the Postgres Database
- Create the Model and the Serializer
- Create All the Endpoints and Methods
- Deployment Setup
- Deploy to Koyeb
Create a Python Virtual Environment
First, we need to set up a local Django project environment. This step involves creating a dedicated virtual environment to manage project-specific dependencies and installing the required packages.
To begin, open your terminal and navigate to the directory where you want to create your Django project:
Next, create a virtual environment using the following command (replace myenv
with your preferred environment name):
This command will create a virtual environment named myenv
in your project directory.
Activate the Virtual Environment
Next, you'll need to activate the virtual environment. Depending on your operating system, use the appropriate command:
On macOS and Linux:
On Windows:
Once activated, you'll notice that your command prompt changes, indicating that you are now working within the virtual environment. This ensures that any packages you install are isolated from your system-wide Python installation.
Install Django and Django REST Framework
With the virtual environment active, we can now install Django and Django REST Framework. Run the following commands:
These commands will install the latest versions of Django and Django REST Framework within your virtual environment.
Now that we have our local Django project environment set up, the next step is to configure Django REST Framework (DRF) and configure our project to use it.
Create a Django Project
Run the following command to create a new Django project:
This command will create a new directory named "urlshortener" in your project directory, and it will contain the initial project structure. Here's what the resulting folder structure will look like:
Configure Django Rest Framework and Set Up the Project
DRF is a powerful toolkit for building Web APIs on top of Django, and it will be essential for creating our URL shortener application.
To use DRF in your Django project, you need to configure it in your project's settings.py
file.
Open your project's settings.py
file, which is typically located in your project's main directory.
Locate the INSTALLED_APPS
list in the settings.py
file. Add rest_framework
to the list of installed apps. It should look like this:
Set Up the Postgres Database
In this step, we'll set up the Postgres database that our URL shortener application will use. In this tutorial, we will be leveraging Koyeb's Managed Postgres.
To create a Managed Postgres database, access your Koyeb control panel and navigate to the Databases tab. Next, click on the Create Database Service button. Here, you can either provide a custom name for your database or stick with the default one, choose your preferred region, specify a default role, or keep the default value, and finally, click the Create Database Service button to establish your Postgres database service.
Once you've created the Postgres database service, a list of your existing database services will be displayed. From there, select the newly created database service, copy the database connection string, and securely store it for future use.
Install Postgres Drivers
Next, you'll need to install Python drivers to connect to the database. The most common Python library for interacting with PostgreSQL is psycopg2
. You can install it using pip:
This library enables Django to communicate with the PostgreSQL database.
Configure the Database
To configure the database for your Django project, we'll use the dj_database_url
library. This library allows you to specify your database configuration using a URL format, making it easy to switch between different database providers.
Install dj_database_url
using pip
:
Open your project's settings.py
file again. Import dj_database_url
at the top of the file:
Locate the DATABASES setting in your settings.py
file and replace it with the following code:
Set the DATABASE_URL
environment variable locally
This configuration tells Django to use the DATABASE_URL
environment variable to determine the database settings.
Linux and macOS (Bash):
Replace "your_database_url_here" with the actual URL or connection string for your Postgres database.
Windows (Command Prompt):
Again, replace "your_database_url_here" with the actual URL or connection string for your Postgres database.
This will set the DATABASE_URL
variable only for the active terminal session, it would need to be set again in any other terminal sessions.
Create the Model and the Serializer
Now that we've set up our Django project and database, it's time to define the core components of our URL shortener: the model and serializer. These components will allow us to manage URLs, track visits, and interact with our API.
Define the URL Model
We'll start by defining the URL
model, which represents the URLs we want to shorten. The model will have three fields:
hash
(string): A unique identifier for the shortened URL.url
(string): The original URL that users want to shorten.visits
(integer): A counter to keep track of the number of times the shortened URL has been visited.
At the root of your Django project, create a new app url
for the model and serializer. Reminder: Django "apps" are subsections of functionality in a Django "project".
Register the App in settings.py
:
Then, open the models.py
file and define the URL
model there:
In this model, we use a CharField
for the hash field, a URLField
for the URL field, and a PositiveIntegerField
for the visits field. The hash field is unique to ensure that each shortened URL is unique.
Create the URL Serializer
Next, create a serializer for the URL model. The serializer defines how the URL model should be serialized into JSON format and vice versa. This is essential for interacting with our API.
In your Django app, create a serializers.py
file. This is where you will define the URLSerializer
:
Here, we create a URLSerializer
class that inherits from serializers.ModelSerializer
. We specify the model as a URL and list the fields we want to include in the serialized representation.
Migrate the database
Run the following commands to migrate your database.
Create All the Endpoints and Methods
In this step, we will create the API endpoints for our URL shortener application and implement the necessary methods behind each endpoint. These endpoints will allow users to shorten URLs, retrieve statistics, and access the original URLs via short hashes.
Redirecting to the Original URL
Endpoint: /url/:hash
This endpoint will handle requests to access the original URL associated with a given hash. We will also increment the visits
count for the URL.
Implementation:
In your views.py
file, create a view to handle the redirection there:
Next, create url/urls.py
and add the URL pattern to map requests to this view:
Creating a New Short URL
Endpoint: /url
This endpoint will allow users to submit a long URL and receive a shortened URL in response.
Implementation:
In your views.py
file, create a view to handle URL creation:
Add the URL pattern for this view in your app's urls.py
file:
Retrieving URL Statistics
Endpoint: /url/stats/:hash
This endpoint will provide statistics about a specific shortened URL, including the number of visits.
Implementation:
In your views.py
file, create a view to retrieve URL statistics:
Add the URL pattern for this view in your app's urls.py
file:
Connecting the URLs
Finally, don't forget to include your app's URLs in your project's urls.py
file. In the project's urls.py
, include your app's URLs using the include function:
Note: This is the urls.py
in your project folder urlshortener
not the urls.py
in the app folder url
. This code connects our app-level URLs to our project-level URLs.
Create the Home Page for the URL Shortener
We have built a functioning API that can be used on its own or used as part of frontend APPs built-in frameworks like React, Svelte, Solid, Qwik, Angular or Vue. In this step, we will add a small UI using Django's built-in templating features.
This UI will:
- Allow you to create new shortened URLs
- Display existing URLs with details
- Display errors if any error occurs in creating a URL like an integrity error if shortening the same URL multiple times.
To start, add a view function to the url/views.py
file that will pull our URLs from the database and send them to a template which will also have a form to generate our URLs.
Create a url/templates
folder and in that folder create an index.html
with the following for our UI:
In the main project urls.py
, import our view and attach it to the main page URL ''.
Test the App Locally
Before deploying your URL shortener to production, it's essential to thoroughly test it locally to ensure that all the endpoints and functionality work as expected. In this step, we'll cover how to test your app on your local development environment.
To start testing your app, make sure your Django development server is up and running. Open your terminal, navigate to your project's root directory, and run the following command:
This command will start the development server at http://localhost:8000
, and you should see output indicating that the server is running.
Deployment Setup
Before deploying your Django application, you need to set up your deployment environment. This includes installing Gunicorn, a WSGI HTTP server for serving your application, and generating a requirements.txt
file to specify the dependencies for your project.
Installing Gunicorn
Gunicorn (short for Green Unicorn) is a popular WSGI HTTP server for running Python web applications. It's a recommended choice for deploying Django applications due to its stability and performance.
You can install Gunicorn using the following command, assuming you have Python and pip installed:
Generating requirements.txt
The requirements.txt
file lists all the Python packages and their versions that your Django application depends on. This file is essential for setting up the same environment in production as you have locally. Here's how to generate a requirements.txt file in different command-line environments:
Run the following command in your project's root directory to generate requirements.txt:
Bash (Mac, Linux):
Command Prompt (CMD - Windows): In the Windows Command Prompt, you can use the following command to generate requirements.txt:
PowerShell (Windows): In PowerShell, use the following command to generate requirements.txt:
This command will create a requirements.txt
file containing a list of installed packages and their versions. It's important to keep this file up-to-date as you add or update dependencies in your Django project. When deploying to Koyeb or other platforms, you can use this file to ensure that the correct dependencies are installed in your production environment.
With Gunicorn installed and your requirements.txt file generated, you're ready to proceed with the deployment of your Django application on Koyeb or your chosen hosting platform.
Specify correct version in runtime.txt
Make sure to specify the right version of Python by creating a runtime.txt file with the following command:
Allowed Hosts Configuration
To ensure the security and functionality of your Django application, you need to specify the allowed hosts that are permitted to access your application. This is achieved by configuring the ALLOWED_HOSTS
setting in your Django project's settings.py
file. Additionally, you should set the environment variable for DJANGO_ALLOWED_HOSTS
during deployment, including your Koyeb URL.
Updating settings.py
-
Open your Django project's
settings.py
file in your code editor. -
Locate the
ALLOWED_HOSTS
setting in the file. By default, it may be commented out or set to an empty list. -
Update the
ALLOWED_HOSTS
setting to dynamically read from an environment variable, allowing you to define the allowed hosts during deployment. Add the following code snippet:
This code sets ALLOWED_HOSTS
to the value of the DJANGO_ALLOWED_HOSTS
environment variable if it is defined. If the environment variable is not set, it falls back to a default list of allowed hosts.
Deploy to Koyeb
Now that you have tested your Django application locally and it's working as expected, it's time to deploy it to production using Koyeb. Koyeb offers flexible deployment options, allowing you to choose between two methods: git-based deployment or Docker-based deployment.
In this tutorial, we will be using the git-driven deployment method. GitHub-based deployment is a convenient way to deploy your Django application to Koyeb.
Create a GitHub Repository to host your Django application's code, called URL-Shortener
. Push your code to your remote repository:
You should now have all your local code in your remote repository.
Within the Koyeb control panel, while on the Overview tab, click Create Web Service to begin:
- Select GitHub as the deployment method.
- Choose the repository that contain your application code.
- In the Builder section, click the Override toggle associated with the Run command and enter
gunicorn urlshortener.wsgi
in the field. - Towards the bottom, choose a name for your App and Service, for example,
url-shortener
. Keep in mind that this name will be used to create the public URL for your application. You'll want to add a shorter custom domain for the base URL. - In the Environment variables section, click Add variable and create the following variables:
DATABASE_URL
with?sslmode=require
added at the end,DISABLE_COLLECTSTATIC
with the value1
, andDJANGO_ALLOWED_HOSTS
with the value{{ KOYEB_PUBLIC_DOMAIN }}
. - Click the Deploy button.
Koyeb will automatically build and deploy your Django application based on changes detected in your GitHub repository.
Once the deployment is complete, you can access your Django REST application by clicking the provided URL ending with .koyeb.app
.
Test the application
Enter a URL in the form and click the Shorten URL button. You should see the endpoint for the original URL in the list. Your application's URL combined with this newly generated endpoint is the new shortened URL. Again, you'll want to configure a shorter, custom domain for this application to make URLs shorter to share.
Conclusion
With your Django application successfully deployed to Koyeb, it becomes accessible to users on the Internet. You can monitor its performance, scale it as needed, and continue enhancing and expanding your web application.
Deploying this application to Koyeb enables you to harness the power of high-performance microVMs, ensuring that your application runs smoothly in the regions where your users are located.
In this guide, we leveraged Koyeb's git-driven deployments. Docker-based deployment offers greater control over your application's environment and dependencies. Docker-based deployments are possible too by adding a Dockerfile to your project's root directory. Choose the deployment method that best aligns with your infrastructure needs and preferences.
Enjoyed this tutorial or have a suggestion to improve it? Share your thoughts with us over on the Koyeb Community.