Most Django tutorials teach you session-based authentication. That works fine when your frontend and backend live on the same server. But the moment you separate them – say, a React app on Netlify talking to a Django API on PythonAnywhere – then sessions start to break down.

Cookies don't travel well across different domains, and suddenly your login system stops working.

That's where JSON Web Tokens (JWT) come in. JWTs give you a stateless, cookie-free way to authenticate users. They work seamlessly across domains, devices, and platforms. The server doesn't need to remember anything. It just verifies the token's signature and knows exactly who's making the request.

But authentication is only half the problem. Once you know who a user is, you still need to control what they can see. This is where scoping comes in.

Scoping means ensuring that each user can only access their own data. User A should never be able to read, edit, or delete User B's data (notes in our case), even if they somehow guess the right ID.

In this tutorial, you'll build a a personal note-taking API where users can register, log in with JWT tokens, and store notes that only they can access.

Along the way, you'll implement a custom user model, configure SimpleJWT for token-based authentication, and write scoped views that lock each user's data behind their own credentials.

What We'll Cover:

• Prerequisities

• What is JWT and Why Use It Over Session Authentication?

  • How Session Authentication Works

  • How JWT Authentication Works

• Step 1: How to Set Up the Project and Install the Dependecies

  • 1.1 How to Create the Project

  • 1.2 How to Create a Virtual Environment and Install the Required Dependencies

  • 1.3 How to Create the Project and the App

  • 1.4 How to Register the App and Django Rest Framework (DRF)

• Step 2: How to Create a Custom User Model

  • 2.1 How to Define the Custom User Model

  • 2.2 How to Tell Django to Use Your Custom User Model

  • 2.3 How to Run Migrations

• Step 3: How to Define the Note Model

  • 3.2 How to Apply Migration

  • 3.3 How to Register Models in the Admin

• Step 4: How to Create the Serializer

  • 4.1 How to Create UserSerializer

  • 4.2 How to Create NoteSerializer

• Step 5: How to Configure SimpleJWT

  • 5.1 How to Update REST Framework Settings

  • 5.2 How to Add Token URL Endpoints

• Step 6: How to Build the Authentication Logic

• Step 7: How to Implement Scoped Views

  • 7.1 How to Create a NoteViewSet

  • 7.2 Why This Matters: Preventing ID Enumeration Attacks

• Step 8: How to Connect a URL

  • 8.1 How to Create App-level URLs

  • 8.2 How to Verify the Project-Level URLs

• Step 9: How to Test the APIs with Postman

  • 9.1 How to Register a User

  • 9.2 How to Obtain Access and Refresh Tokens

  • 9.3 How to Create a Note

  • 9.4 How to List Your Notes

  • 9.5 How to Demostrate Scoping

• Step 10: How to Handle Token Expiration with Refresh Tokens

• How You Can Improve This Project

• Conclusion

Here's what this tutorial covers:

1. How to set up a custom user model (and why you should always do this)

2. How to configure SimpleJWT for access and refresh token authentication

3. How to build serializers that protect sensitive fields

4. How to scope your API views so users only see their own data

5. How to test the entire flow using Postman

Let's get started

Prerequisities

Before you begin, make sure you're comfortable with the following:

1. Django fundamentals: You should understand how Django projects and apps work, including models, views, URLs, and migrations.

2. Django REST Framework basics: You should be familiar with serializers, viewsets or API views, and how DRF handles requests and responses.

3. Basic command line usage: You'll run commands in your terminal throughout this tutorial.

Tools you'll need installed:

• Python 3.8 or higher

• pip (Python's package manager)

• A code editor like Visual Studio Code

• Postman (or any API testing tool) for testing your endpoints. You'll use this to send requests to your API.

What is JWT and Why Use It Over Session Authentication?

Before you write any code, it's important to understand what problem JWTs solve and why Django's built-in session authentication isn't always enough.

How Session Authentication Work

Django ships with a session-based authentication system. Here's how it works at a high level:

1. A user sends their username and password to the server.

2. The server verifies the credentials and creates a session which is a small record stored in the server's database that says "this user is logged in."

3. The server sends back a session ID as a cookie. The browser stores this cookie automatically.

4. On every subsequent request, the browser sends the cookie back to the server. The server looks up the session ID in its database and says "ah, this is User A. Let them through."

This works perfectly when your frontend and backend live on the same domain. The browser handles cookies automatically, and Django manages sessions in the database without you thinking about it.

But this approach has some limitations.

1. The cross-domain problem: If your React frontend lives at app.example.com and your Django API lives at api.example.com, cookies become tricky. Browsers enforce strict rules about which domains can send and receive cookies.

   You can work around this with CORS (Cross-Origin Resource Sharing) headers and special cookie settings, but it adds complexity and can be fragile.

2. The scalability problem: Every active session is stored in the server's database. If you have 10,000 users logged in at the same time, that's 10,000 session records the server has to look up on every single request. As your application grows, this lookup becomes a bottleneck.

3. The mobile problem: Mobile apps don't handle cookies the same way browsers do. If you're building an API that will serve both a web app and a mobile app, session cookies create extra headaches.

How JWT Authentication Works

JWTs take a fundamentally different approach. Instead of storing session data on the server, they put the authentication information directly into the token itself.

Here's how the flow works:

1. A user sends their username and password to the server.

2. The server verifies the credentials and creates a JWT – a long encoded string that contains information like the user's ID and when the token expires.

3. The server sends this token back to the client. The client stores it (usually in memory or local storage).

4. On every subsequent request, the client includes the token in the request header. The server reads the token, verifies its signature, and says "this is User A. Let them through."

Notice the key difference: the server never stores anything.

It doesn't look up a session in a database. It simply reads the token, checks its cryptographic signature to make sure nobody tampered with it, and extracts the user information. That's why JWTs are called stateless – the server doesn't maintain any state about who is logged in.

This solves the cross-domain problem because tokens are sent in the request header, not as cookies. Headers work the same way regardless of which domain the request comes from.

This solves the scalability problem because the server doesn't store sessions. Verifying a token is a quick cryptographic check, not a database lookup.

This solves the mobile problem because any client that can send HTTP headers can use JWT. Mobile apps, desktop apps, other servers – they all work the same way.

Step 1: How to Set Up the Project and Install the Dependecies

1.1 How to Create the Project

Open your terminal, navigate to where you want your project to live, and run the following commands:

mkdir notes-project

cd notes-project

1.2 How to Create a Virtual Environment and Install the Required Dependencies

You will create a virtual environment here. Type the following command:

python3 -m venv venv

The above command creates a virtual environment inside a folder called venv. The first venv is the command and the second venv represents the name of the folder. You can name the folder anything though venv is usually preferred.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

With the virutal environment activated, install Django, Django Rest Framework, and Simple JWT Framework using the command:

pip install django djangorestframework djangorestframework-simplejwt 

You can verify everything installed correctly by running:

pip list

You should see all three packages listed along with their dependencies.

1.3 How to Create the Project and the App

Run the following command to create the Django project:

django-admin startproject notes_core .

The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now let's type this command to create the app:

python manage.py startapp notes

1.4 How to Register the App and Django Rest Framework (DRF)

Open notes_core/settings.py and add rest_framework and notes in the INSTALLED_APPS list:

Django now knows about your new app and the REST framework. Let's move on to the most important architectural decision you'll make for this project.

Step 2: How to Create a Custom User Model

If you've built Django projects before, you might have used Django's default User model. For quick prototypes, that works fine. But for any project you plan to grow or maintain, starting with a custom user model is a best practice you should never skip.

Here's why: Django's default User model uses a username field as the primary identifier. If you later decide you want users to log in with their email address instead, or you need to add a profile picture field, or a phone number, then you're stuck.

Using a custom user model gives you full control over what a "user" means in your app. Instead of being tied to a username, you can design login around something more practical, like email or phone_number for a fitness or mobile-based app. You can also include fields like role (doctor, patient, receptionist in a clinic system) or date of birth directly in the user model, instead of managing a separate profile.

It also helps future-proof your project. If you start with the default model and later decide to switch login from username to email, or add required fields, it becomes difficult and risky to change. Using a custom user model from the beginning avoids this problem and makes it much easier to adapt your authentication system as your app grows.

By creating a custom user model from the start, even if it's identical to the default one, you give yourself the freedom to make changes later without any of that pain.

2.1 How to Define the Custom User Model

Open notes/models/py and add the following code:

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    pass

You are importing Django’s built-in AbstractUser class.

Think of AbstractUser as a ready-made blueprint for a user. It already includes fields like username, password, email, first name, last name , and authentication logic.

The pass statement means you're not adding any extra fields yet.

But the key point is that this model is yours. So this model behaves exactly like Django’s default user model, but with one big advantage: you now have the flexibility to customize it later.

If three months from now you need to add a phone_number field or switch to email-based login, you just add a field to this class and run a migration.

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    phone_number = models.CharField(max_length=15)

You can also see all the fields that the CustomUser class has inherited from the AbstractUser class.

To do this we can use the Python shell. Type the following command:

python manage.py shell

When you type this command, make sure that the virtual environment is active:

After this, import the CustomUser model in the shell:

from notes.models import CustomUser

After that, type the following code:

[fields.name for field in CustomUser._meta.get_fields()]

The above statement lists out all the fields in the CustomUser class.

2.2 How to Tell Django to Use Your Custom User Model

Now comes the important bit. Open notes_core/settings.py and add this line:

AUTH_USER_MODEL = 'notes.CustomUser'

This setting tells Django to use your CustomUser model instead of the built-in one for everything authentication-related such as login, permissions, foreign keys, and so on.

There's no strict rule to where you need to add it, but the best practice is to add it near the end of the file.

You can see which user model Django is using by using the method get_user_model().

Open the Python shell again and import the get_user_model() method:

from django.contrib.auth import get_user_model 

Then use get_user_model() and print the output:

user = get_user_model()
print(user)

You should see the name of our model being used:

If you hadn't added the AUTH_USER_MODEL in the settings.py file, then Django would have used the default user model:

Note: You'll need to do this before you run your first migration. If you run migrate before setting AUTH_USER_MODEL, Django creates tables for the default User model, and switching afterward becomes a headache.

2.3 How to Run Migrations

Now create and apply the initial migrations:

python manage.py makemigrations
python manage.py migrate

Django will create the necessary tables for your custom user model along with all the built-in Django tables.

We can again peek under the hood to see the SQL queries that Django used to create the tables especially the CustomUser table.

Type this command:

python manage.py sqlmigrate notes 0001

Here notes is the name of the app and 0001 represents the migration number.

And you should get this output:

Let's also create a superuser so you can access the admin panel later for debugging:

python manage.py createsuperuser

Fill in the username, email (optional), and password when prompted.

Step 3: How to Define the Note Model

Now let's create the data model for the core of your application. First add a new import to use the settings object.

from django.conf import settings

Then add the following code below the CustomUser class:

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Here's the complete model.py code:

from django.contrib.auth.models import AbstractUser
from django.db import models
from django.conf import settings

class CustomUser(AbstractUser):
    pass

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Let's walk through each field:

1. owner = models.ForeignKey(settings.AUTH_USER_MODEL, ...): Creates a relationship between each note and a user. The ForeignKey field tells Django that each note belogs to exactly one user but a user can have many notes.

   Notice that we use settings.AUTH_USER_MODEL instead of directly importing CustomUser. This is the recommended practice because it keeps your code flexible. If you ever change the user model reference in settings, this foreign key adapts automatically.

   The on_delete=models.CASCADE means that if a user is deleted, all their notes are deleted too.

   The related_name='notes' lets you access a user's notes with user.notes.all().

2. title = models.CharField(max_length=200): Creates a text field for the task name, limited to 200 characters.

3. body = models.TextField(): Holds the actual note content. TextField has no character limit, so users can write as much as they need.

4. created_at = models.DateTimeField(auto_now_add=True): Automatically records the date and time when a task is created. You never need to set this manually.

   The __str__() method gives each note a readable representation. Instead of seeing "Note object (1)" in the admin panel or during debugging, you'll see something like "Meeting Notes (by Solina)."

3.2 How to Apply Migration

Run the migration commands to create the Note table:

python manage.py makemigrations
python manage.py migrate

As before, we can see the exact SQL query Django used to create the notes table:

3.3 How to Register Models in the Admin

Open notes/admin.py and register both models so you can inspect data through the admin panel:

from django.contrib import admin
from .models import CustomUser, Notes

admin.site.register(CustomUser)
admin.site.register(Notes)

This is helpful during development when you want to quickly check whether data is being saved correctly.

Step 4: How to Create the Serializer

In DRF, a serializer is like a bridge between your database and the internet.

Django models store data as Python objects. But when you want to send that data to a frontend application (like React or a mobile app), you can't send Python objects. You need to send a format that everyone understands which is usually JSON.

Serializers perform three main jobs:

1. Serialization: Converting complex Python objects (Models) into Python dictionaries (which can be easily rendered into JSON).

2. Deserialization: Converting JSON data coming from a user back into complex Python objects.

3. Validation: Checking if the incoming data is correct before saving it to the database.

4.1 How to Create UserSerializer

Create a new file called notes/serializers.py and add the following code:

from rest_framework import serializers
from django.contrib.auth import get_user_model

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)

    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

Let's break down this serializer.

1. The UserSerializer handles user registration.

2. User = get_user_model() gets the user model that you're using and stores in the variable User. In our case, we're using the CustomUser model

3. class UserSerializer(serializers.ModelSerializer):: Here you've created the UserSerializer class, which inherits ModelSerializer.

   A ModelSerializer is a shortcut that automatically creates a serializers class with fields that are in the model class.

   When we use a ModelSerializer, DRF inspects the model and automatically does these things:

   1. Generates fields from the model so you don't have to
   2. Automatically adds field validations that are present in the model
   3. Implements create() and update() methods. A ModelSerializer knows which model to use and how to update and create it. You can override create() and update() methods if you need customized behaviors. You have overridden the create() method in the above code.

4. password = serializers.CharField(write_only=True): This line is crucial. The write_only=True flag means the password will be accepted during registration but will never appear in any API response. Without this, your API would send back the password (even if hashed) every time user data is returned.

   So users can create accounts, but their passwords are never exposed back.

5. class Meta: Inside the Meta class, you tell the serializer which model to use. In this case, the model to use is User and the fields to be handled.

6. The create() method: This is the most important part. This method runs when we create a new user. Instead of using the default .create() method you have overridden it.

   It's important to understand why we have overridden this method. The default create() method is not suitable for creating users securely.

   By default this method stores the password in plain text format. This is a serious problem because passwords should never be stored in raw form. They need to be hashed so that even if the database is compromised, the passwords are never exposed.

   Django provides a special method called create_user() that automatically handles this by hashing the password and setting up the user properly for authentication.

4.2 How to Create NoteSerializer

After the UserSerializer class, let's create the NoteSerializer class. The NoteSerializer handles the notes data

First of all, you need to add an import to the Notes class. Add the line from .models import Notes at the end of the last import.

Put this code below the UserSerializer class:

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Now let's break it down:

1. owner = serializers.ReadOnlyField(source='owner.username'): This is the most important line in the code. This makes the owner field read-only. That means the API will display who owns a note (showing their username), but no one can set or change the owner through the API.

   Without this protection, a malicious user could send a POST request with "owner": 5 and assign their note to someone else's account, or worse, modify someone else's notes by reassigning ownership.

   The source='owner.username' part tells DRF to display the owner's username instead of their numeric ID, which makes the API responses more readable.

2. class Meta: ...: As before the Meta class contains the model which the serializer use and the fields that the API will expose.

   Here is the complete code in the serializers.py file

from rest_framework import serializers
from django.contrib.auth import get_user_model
from .models import Notes

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)
    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Step 5: How to Configure SimpleJWT

Now let's set up the authentication system. This is where you tell DRF to use JWT for authentication instead of sessions. This step is crucial because without it, DRF will default to session-based auth.

SimpleJWT provides a complete JWT implementation for DRF, so you don't have to build token generation, signing, or verification from scratch.

The access token is what your client sends with every API request. It's short-lived by design. Think of it like a visitor badge at an office building: it gets you through the door, but it expires at the end of the day. If someone steals it, the damage is limited because it stops working soon.

The refresh token is longer-lived and has a single purpose: getting a new access token when the current one expires. The client stores it securely and only sends it to one specific endpoint. Think of it like your employee ID card. You use it to get a new visitor badge each morning, but you don't flash it at every door.

This separation exists for security. If the short-lived access token is compromised (which is more likely since it's sent with every request), the attacker has a narrow window before it expires. The refresh token, which is sent less frequently, has a lower risk of interception.

Let's look at how the access and refresh token work together

1. User logs in, server gives both access token and refresh token

2. User makes requests using the access token

3. Access token expires

4. App sends refresh token to server

5. Server checks it and gives a new access token

6. User continues without logging in again

5.1 How to Update REST Framework Settings

Open notes_core/settings.py and add the following code:

from datetime import timedelta
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),

    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=30),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}

Let's unpack what each section does.

The DEFAULT_AUTHENTICATION_CLASSES setting tells DRF to use JWT as the authentication method for all API endpoints. Every incoming request will be checked for a valid JWT token in the Authorization header.

The DEFAULT_PERMISSION_CLASSES setting sets IsAuthenticated as the global permission policy. This means every endpoint in your API is locked down by default. Only users with a valid token can access any endpoint.

This is a secure-by-default approach: instead of remembering to protect each view individually, everything is protected, and you explicitly open up the endpoints that need to be public (like the registration endpoint, which you'll handle in the next step).

The SIMPLE_JWT dictionary controls token behavior. The access token lasts 30 minutes. This is the token clients include in every request. If someone intercepts it, the damage is limited to a 30-minute window. The refresh token lasts one day.

When the access token expires, the client can use the refresh token to get a new access token without forcing the user to log in again. The duration of the refresh token is 1 day. This means after 1 day, the user must log in again with their username and password. You'll see exactly how this works later when you test with Postman.

5.2 How to Add Token URL Endpoints

SimpleJWT provides ready-made views for obtaining and refreshing tokens. You just need to wire them up to URLs.

Open notes_core/urls.py and update it with the following code:

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

The token/ endpoint accepts a username and password, and returns an access token and a refresh token.

The token/refresh/ endpoint accepts a refresh token and returns a new access token. You'll see these in action during testing.

Step 6: How to Build the Authentication Logic

Open notes/views.py and add the following:

from rest_framework import generics, permissions
from django.contrib.auth import get_user_model
from .serializers import UserSerializer

User = get_user_model()

class RegisterView(generics.CreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [permissions.AllowAny]

Now let's walk through this code.

The first section are the imports and after that we have used the the get_user_model() method to get the CustomUser model.

Now the main part is RegisterView class. The class inherits from generics.CreateAPIView which is a built in DRF view designed specifically for handling POST requests that create new objects.

Because of this, you don’t have to manually write the logic for handling POST requests, validating data, or saving to the database. DRF does all of that for you behind the scenes.

Inside the class, queryset = Users.objects.all() defines the set of user objects this view can work with.

The serializer_class = UserSerializer tells the view which serializer to use for validating incoming data and creating the user.

Finally permission_classes = [permissions.AllowAny] overrides the global IsAuthenticated permission you set earlier in the value of DEFAULT_PERMISSION_CLASSES .

This means that anyone can access the registration endpoint, even if they aren't logged in. This makes sense for a registration endpoint because new users won’t have accounts yet.

Every other view in your API will inherit the global IsAuthenticated permission, so only this registration endpoint is open.

Step 7: How to Implement Scoped Views

This is the heart of the tutorial. You've set up authentication so the API knows who is making a request. Now you need to make sure each user can only interact with their own notes.

Think of it this way: authentication is the lock on the front door of an apartment building. It keeps strangers out. But scoping is the lock on each individual apartment. Just because you live in the building doesn't mean you can walk into your neighbor's apartment.

Without scoping, an authenticated user could potentially see every note in the database, or worse, modify notes that belong to someone else. Two method overrides on your viewset prevent this entirely.

7.1 How to Create a NoteViewSet

Now let's create the NoteViewSet. First add these imports to the top of the file. We're importing the viewsets, serializers, and model.

from .models import Note
from .serializers import UserSerializer, NoteSerializer
from rest_framework import generics, viewsets, permissions

Add the following to notes/views.py, below the RegisterView:

class NoteViewSet(viewsets.ModelViewSet):
    serializer_class = NoteSerializer

    def get_queryset(self):
        return Notes.objects.filter(owner=self.request.user).order_by('-created_at')

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)

Now let's talk about this code in detail.

You've created a new class called NoteViewSet which inherits from the DRF class ModelViewSet. This gives you full CRUD operations, meaning you can list notes and retrieve a single note, as well as create, update, and delete a note.

The next part serializer_class = NoteSerializer tells Django to use the NoteSerializer class to convert between Python objects and JSON.

But the magic is the two methods that you are overriding: get_queryset() and perform_create().

The get_queryset() method controls which notes the API returns. If you didn't override this method, it would return Note.objects.all() (which would give every user access to every note in the database).

But here, you've overridden this method so that it filters notes by the current user.

Next is the perform_create() method, which is called when the note is saved. You've overridden this method so that it saves the notes of the user who's currently logged in. If you hadn't overridden the this method, it would return all the notes regardless of the logged in user.

Notice that you have passed self.request.user parameters in to the filter() function. This is the code that attaches the logged-in user as the owner of the note.

Remember how you made the owner field read-only in the serializer? This is the other half of that security measure.

The user can't set the owner through the API request, and the server automatically sets it to whoever is authenticated. These two pieces work together to make ownership tamper-proof.

7.2 Why This Matters: Preventing ID Enumeration Attacks

Without get_queryset filtering, your API might allow something like this: a user sends a GET request to /api/notes/42/ and sees a note that belongs to someone else, simply because they guessed the ID.

This is called an ID enumeration attack — an attacker cycles through IDs (1, 2, 3, 4...) to discover and access other people's data.

With your scoped get_queryset, even if User B sends a request to /api/notes/42/ and note 42 belongs to User A, the viewset won't find it in User B's filtered queryset. DRF will return a 404 — as far as User B is concerned, that note doesn't exist.

Step 8: How to Connect a URL

Now you need to wire up the views to URL paths so the API knows which view to call for each endpoint.

8.1 How to Create App-level URLs

Create a new file called notes/urls.py and add the following:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import RegisterView, NoteViewSet

router = DefaultRouter()
router.register(r'notes', NoteViewSet, basename='note')

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('', include(router.urls)),
]

The DefaultRouter automatically generates URL patterns for the NoteViewSet. Since you're using a ModelViewSet, the router creates endpoints for listing all notes, creating a note, retrieving a single note, updating a note, and deleting a note — all from that single router.register call.

The basename='note' parameter is required here because your viewset doesn't have a queryset attribute defined directly on the class (you're using get_queryset instead). DRF uses the basename to generate the URL pattern names like note-list and note-detail.

8.2 How to Verify the Project-Level URLs

Make sure your notes_core/urls.py looks like this (you set this up in Step 5, but let's confirm):

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

Here's the full picture of your API's URL structure:

Start the development server to make sure everything runs without errors:

python manage.py runserver

If the server starts without complaints, your code is wired up correctly.

Step 9: How to Test the APIs with Postman

Building the API is one thing. Proving it works is another. Let's walk through the entire flow using Postman, from registering a user to demonstrating that scoping actually works.

If you haven't used Postman before, it's a tool that lets you send HTTP requests to your API and inspect the responses. You can download it from postman.com/downloads.

Alternatively, you can use curl from the command line or any other API testing tool you're comfortable with.

Make sure your development server is running before proceeding.

9.1 How to Register a User

Open Postman:

Create a new request:

Click Send. You should get a 201 Created response with the user data (without the password, thanks to your write_only=True field) which you wrote in the UserSerializer class.

9.2 How to Obtain Access and Refresh Tokens

Now log in to get your JWTs:

You'll get a response with access and refresh tokens.

Copy the access token. You'll need it for every subsequent request. Also save the refresh token, as you'll use it later.

A JWT is only encoded and not encrypted. The encoding is merely a way to transform the data into a safe, standard string format that can be easily transmitted over the internet.

Any one can peel through the encoding to see the data. This is done using base64url encoding.

We can use the Python library pyjwt to decode JWTs or use any of the online sites to decode. It's important to note that you should use online sites with caution since JWTs may contain sensitive information.

For this demo, we'll use site called jwt.io.

Open the site and paste in the access token that you have just created:

The JWT has three parts: the header, the payload, and the signature.

The header sections tells you how the header is signed. In this case it is signed using the HS256 algorithm.

The payload is where the actual data or claim lives. It contains standard claims such as token types, expiration time ( exp ), issued at time ( iat ), and custom claims.

The signature section is used to verify integrity. You can't decode it to meaningful data. This section ensures that the token wasn't tampered with.

9.3 How to Create a Note

Now use the access token to create a note:

Notice that you don't include an owner field. That's handled automatically by perform_create. You should get a 201 Created response:

You can create a few more notes, so that we have some data to work with.

9.4 How to List Your Notes

Now to fetch all of Priya's notes:

You should see all the notes created, sorted by most recent first.

9.5 How to Demonstrate Scoping

Let's prove that a second user can't view the first user's notes.

First, register the second user.

Send a POST request to http://127.0.0.1/api/register with the following data:

Then get tokens for Sujan by sending a POST request to http://127.0.0.1:8000/api/token/ with Sujan's credentials (username and password) and then copy Sujan's access token.

Now send a GET request to http://127.0.0.1:8000/api/notes/ using Sujan's token in the Authorization header.

The response should be an empty list since this user hasn't created any notes:

More importantly, Priya's notes are completely invisible to him. Even if Sujan tries to access a specific note by ID – say, http://127.0.0.1:8000/api/notes/1/ – he'll get a 404 Not Found response, not a 403 Forbidden.

This is intentional. A 404 Not Found doesn't reveal that the note exists, while a 403 Forbidden would confirm its existence to a potential attacker.

A 403 Forbidden response is like a door with a sign: “Authorized personnel only”. You now know something important is inside. A 404 Not Found response is like a blank wall. You don’t even know a room exists.

Now that you know why we've used the 404 response instead of 403, let's demonstrate this.

First, I'll access Priya's individual note using her credentials and her access token:

Now, I'll change the access token and put Sujan's (new user) access token:

You can see that using the new user's token to access the previous user's note leads to 404 Not Found response.

Step 10: How to Handle Token Expiration with Refresh Tokens

Access tokens are deliberately short-lived (30 minutes in your configuration). This limits the window of damage if a token is stolen.

But you don't want users to re-enter their credentials every 30 minutes. That's what refresh tokens are for.

When Priya's access token expires, her API requests will start returning 401 Unauthorized responses. Instead of logging in again, the client sends the refresh token to get a fresh access token.

Replace your old access token with this new one, and you're good for another 30 minutes. The refresh token itself lasts for one day, so the user only needs to fully log in again once every 24 hours.

In a real application, the frontend client handles this automatically. When an API call returns a 401, the client catches it, sends the refresh token to get a new access token, and retries the original request — all without the user noticing.

Here's what that flow looks like in pseudocode:

1. Client sends request with access token

2. Server responds with 401 (token expired)

3. Client sends refresh token to /api/token/refresh/

4. Server responds with a new access token

5. Client retries the original request with the new access token

6. Server responds with the data

   

If the refresh token itself has expired (after 24 hours in your configuration), step 4 will also return a 401. At that point, the user truly needs to log in again with their username and password. This is the intended behavior: it means even a stolen refresh token has a limited useful life.

How You Can Improve This Project

This API is functional and secure, but there's plenty of room to build on it. Here are some directions you could take.

1. Add search and filtering. Let users search their notes by title or body text. You can use DRF's SearchFilter and django-filter to add query parameters like ?search=meeting to the notes list endpoint.

2. Add categories or tags. Create a Category model and add a foreign key to Note, or use a many-to-many relationship for tags. This would let users organize their notes and filter by category.

3. Add pagination. Once a user has hundreds of notes, returning them all in a single response becomes slow. DRF has built-in pagination classes that let you return notes in pages of 10, 20, or whatever size you choose.

4. Deploy to a production server. The API currently runs on your local machine. You could deploy it to platforms like PythonAnywhere, Railway, or Render to make it accessible from anywhere. You'd need to configure a production database (like PostgreSQL), set a secure SECRET_KEY, and serve the application behind HTTPS.

5. Build a frontend. Connect a React, Next.js, or Vue.js frontend to this API. Store the JWTs in the client and implement the token refresh flow so users stay logged in seamlessly.

6. Add token blacklisting. SimpleJWT supports token blacklisting, which lets you invalidate refresh tokens when a user logs out. Without this, a refresh token remains valid until it expires, even after the user "logs out."

Each of these improvements builds on the patterns you've already learned and will deepen your understanding of Django, DRF, and API design.

Conclusion

You've built a fully functional, secure note-taking API with Django, Django REST Framework, and SimpleJWT. Along the way, you learned some fundamental concepts that apply to any API you'll build in the future.

You started with a custom user model — a small decision at the beginning that saves you from a painful migration later. You configured JWT authentication so your API can serve mobile clients and decoupled frontends that can't rely on session cookies.

You built serializers that protect sensitive data by keeping passwords write-only and ownership read-only. Most importantly, you implemented scoped views that ensure each user's data is completely isolated from everyone else's.

The patterns you practiced here — overriding get_queryset to filter by the current user, overriding perform_create to assign ownership automatically, and using read-only fields to prevent data tampering — are the same patterns you'll use in production APIs handling real user data.

The best way to solidify what you've learned is to keep building. Try adding search and filtering, build a React frontend that consumes this API, or start a completely new project may be a task manager, a journal app, or a bookmarks API using the same JWT and scoping patterns. The core workflow stays the same. Only the models and business logic change.

There are three dominant patterns: REST over HTTP, gRPC with Protocol Buffers, and event-driven messaging through a broker. Most production systems use a mix of all three. The skill is knowing which pattern fits which interaction.

In this article, you'll learn the core mechanics of each communication style, the real trade-offs between them across five dimensions (latency, coupling, schema evolution, debugging, and operational complexity), and a decision framework for choosing the right pattern for each service interaction.

Prerequisites

To get the most out of this article, you should be familiar with:

• Basic HTTP concepts (request/response, status codes, headers)

• Working with APIs in any backend language (the examples use TypeScript and Node.js)

• General understanding of microservices architecture

• Familiarity with JSON as a data interchange format

Table of Contents

• The Three Patterns at a Glance

• REST: The Default Choice

• gRPC: The Performance Choice

• Event-Driven Messaging: The Decoupling Choice

• The Five Trade-Off Dimensions

• The Decision Framework

• Hybrid Architectures: Using All Three

• Schema Governance at Scale

• Conclusion

The Three Patterns at a Glance

Before diving deep, here's the landscape:

Each has strengths, and none is universally better. The rest of this article explores why.

REST: The Default Choice

REST over HTTP is the most widely understood communication pattern. Services expose resources at URL endpoints, and clients interact through standard HTTP methods.

// Order service calls the inventory service
async function checkInventory(productId: string): Promise<InventoryStatus> {
  const response = await fetch(
    `https://inventory-service/api/v1/products/${productId}/stock`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${getServiceToken()}`,
      },
    }
  );

  if (!response.ok) {
    throw new HttpError(response.status, await response.text());
  }

  return response.json();
}

Where REST Excels

Every language, framework, and platform speaks HTTP. Your frontend, your mobile app, your partner integrations, and your internal services can all use the same protocol.

The tooling is also mature: load balancers, API gateways, caching proxies, and debugging tools all understand HTTP natively.

It's also relatively simple. A new developer can read a REST call and understand what it does. The URL describes the resource. The HTTP method describes the action. The status code describes the outcome. There's no schema compilation step, no code generation, and no special client library required.

Beyond this, HTTP has built-in caching semantics. A GET /products/123 response with a Cache-Control: max-age=60 header can be cached by every proxy between the caller and the server. gRPC and event-driven patterns have no equivalent built-in mechanism.

// REST response with cache headers
app.get("/api/v1/products/:id", async (req, res) => {
  const product = await getProduct(req.params.id);

  res.set("Cache-Control", "public, max-age=60");
  res.set("ETag", computeETag(product));

  res.json(product);
});

Where REST Falls Short

REST's resource-oriented model often requires multiple round-trips to assemble a response. Fetching an order with its items, customer details, and shipping status might mean three separate HTTP calls. Each call adds network latency, TCP handshake overhead, and serialization cost.

// Three sequential calls to build one view
async function getOrderDetails(orderId: string): Promise<OrderDetails> {
  const order = await fetch(`/api/orders/${orderId}`).then((r) => r.json());
  const customer = await fetch(`/api/customers/${order.customerId}`).then((r) => r.json());
  const shipment = await fetch(`/api/shipments/${order.shipmentId}`).then((r) => r.json());

  return { order, customer, shipment };
}

You can mitigate this with composite endpoints or GraphQL, but that adds complexity. gRPC handles this more naturally with message composition.

The serialization overhead is also an issue. JSON is human-readable but expensive to parse. For high-throughput internal communication where nobody reads the payloads, you are paying a tax in CPU and bandwidth for readability you do not need.

Finally, there's no streaming. Standard REST is request-response. If you need the server to push updates to the client (real-time order tracking, live metrics), REST requires workarounds like polling, Server-Sent Events, or WebSockets. None of these are part of the REST model itself.

gRPC: The Performance Choice

gRPC is a Remote Procedure Call framework built on HTTP/2 and Protocol Buffers. Instead of URLs and JSON, you define services and messages in .proto files, and the framework generates strongly-typed client and server code.

Defining the Contract

// inventory.proto
syntax = "proto3";

package inventory;

service InventoryService {
  // Unary: single request, single response
  rpc CheckStock(StockRequest) returns (StockResponse);

  // Server streaming: single request, stream of responses
  rpc WatchStockLevels(WatchRequest) returns (stream StockUpdate);

  // Client streaming: stream of requests, single response
  rpc BulkUpdateStock(stream StockAdjustment) returns (BulkUpdateResult);
}

message StockRequest {
  string product_id = 1;
  string warehouse_id = 2;
}

message StockResponse {
  string product_id = 1;
  int32 available = 2;
  int32 reserved = 3;
  google.protobuf.Timestamp last_updated = 4;
}

message StockUpdate {
  string product_id = 1;
  int32 available = 2;
  string warehouse_id = 3;
}

After running protoc (the Protocol Buffer compiler), you get generated client and server stubs in your target language. The TypeScript client looks like this:

import { InventoryServiceClient } from "./generated/inventory";
import { credentials } from "@grpc/grpc-js";

const client = new InventoryServiceClient(
  "inventory-service:50051",
  credentials.createInsecure()
);

async function checkStock(productId: string): Promise<StockResponse> {
  return new Promise((resolve, reject) => {
    client.checkStock(
      { productId, warehouseId: "warehouse-eu-1" },
      (error, response) => {
        if (error) reject(error);
        else resolve(response);
      }
    );
  });
}

Where gRPC Excels

Protocol Buffers serialize to a compact binary format. A message that is 1 KB as JSON might be 300 bytes as Protobuf. Combined with HTTP/2 multiplexing (multiple requests over a single TCP connection), gRPC delivers significantly lower latency and higher throughput than REST for internal service calls. And we all know performance is important.

The exact improvement depends on payload size, network topology, and server implementation. In benchmarks, the difference ranges from marginal (tiny payloads on fast networks) to an order of magnitude (large payloads, high concurrency).

The takeaway: gRPC's binary serialization and HTTP/2 multiplexing give it a structural advantage for internal traffic, but you should measure in your own environment before making latency claims.

Also, gRPC natively supports four communication patterns: unary (request-response), server streaming, client streaming, and bidirectional streaming. This makes it a natural fit for real-time use cases like live stock updates, log tailing, or progress reporting.

// Server streaming: watch inventory changes in real time
function watchStockLevels(warehouseId: string): void {
  const stream = client.watchStockLevels({ warehouseId });

  stream.on("data", (update: StockUpdate) => {
    console.log(`Product \({update.productId}: \){update.available} available`);
  });

  stream.on("error", (error) => {
    console.error("Stream error:", error.message);
    // Reconnect logic here
  });

  stream.on("end", () => {
    console.log("Stream ended");
  });
}

Finally, it has strong typing across services. The .proto file is the single source of truth. Both the client and server are generated from it. If the inventory service changes the StockResponse message, the order service's build fails until it regenerates its client. You catch breaking changes at compile time, not at 3 AM.

Where gRPC Falls Short

The first key issue is browser support. Browsers can't make native gRPC calls because the browser's fetch API doesn't expose the HTTP/2 framing that gRPC requires (for example, trailers for status codes and fine-grained control over bidirectional streams).

You need gRPC-Web, which uses a proxy like Envoy to translate between the browser-compatible subset of gRPC and the full protocol. Alternatively, you can place a REST or GraphQL gateway in front of your gRPC services.

Either way, gRPC isn't a viable choice for any endpoint that a browser calls directly — which is why the decision framework in this article defaults to REST for public-facing APIs.

It's also difficult to debug. You can't curl a gRPC endpoint. The binary payloads aren't human-readable. Tools like grpcurl and Postman's gRPC support help, but the debugging experience is worse than inspecting a JSON response in a browser's network tab.

# Debugging a REST endpoint
curl -s https://inventory-service/api/v1/products/abc-123/stock | jq

# Debugging a gRPC endpoint (requires grpcurl)
grpcurl -plaintext -d '{"product_id": "abc-123"}' \
  inventory-service:50051 inventory.InventoryService/CheckStock

Finally, operational overhead is an issue. You need to manage .proto files, run code generation in your build pipeline, version your proto definitions, and ensure all consumers regenerate when schemas change.

For a team with two services, this is manageable. For twenty services, you need a proto registry and a governance process.

Event-Driven Messaging: The Decoupling Choice

Event-driven communication flips the model. Instead of service A calling service B directly, service A publishes an event to a broker (Kafka, RabbitMQ, Amazon SNS/SQS, or similar), and service B consumes it asynchronously.

// Order service publishes an event after confirming an order
import { Kafka } from "kafkajs";

const kafka = new Kafka({ brokers: ["kafka:9092"] });
const producer = kafka.producer();

async function publishOrderConfirmed(order: Order): Promise<void> {
  await producer.send({
    topic: "order.confirmed",
    messages: [
      {
        key: order.id,
        value: JSON.stringify({
          eventType: "order.confirmed",
          eventId: crypto.randomUUID(),
          timestamp: new Date().toISOString(),
          data: {
            orderId: order.id,
            customerId: order.customerId,
            items: order.items.map((item) => ({
              productId: item.productId,
              quantity: item.quantity,
            })),
            total: order.total,
          },
        }),
      },
    ],
  });
}

// Inventory service consumes the event independently
const consumer = kafka.consumer({ groupId: "inventory-service" });

async function startInventoryConsumer(): Promise<void> {
  await consumer.subscribe({ topic: "order.confirmed" });

  await consumer.run({
    eachMessage: async ({ message }) => {
      const event = JSON.parse(message.value.toString());

      for (const item of event.data.items) {
        await decrementStock(item.productId, item.quantity);
      }

      logger.info("Inventory updated for order", {
        orderId: event.data.orderId,
      });
    },
  });
}

Where Event-Driven Excels

First, it employs temporal decoupling. The producer doesn't wait for the consumer. The order service publishes "order confirmed" and moves on. If the inventory service is down, the event sits in the broker until it recovers. No timeout, no retry logic in the producer, no cascading failure.

One event can also trigger multiple independent reactions. When an order is confirmed, the inventory service decrements stock, the notification service sends a confirmation email, the analytics service records a conversion, and the shipping service starts fulfillment. The order service doesn't know or care about any of these consumers.

order.confirmed event
  ├── inventory-service    → Decrement stock
  ├── notification-service → Send confirmation email
  ├── analytics-service    → Record conversion
  └── shipping-service     → Create shipment

Adding a new consumer requires zero changes to the producer. This is the lowest coupling you can achieve between services.

There's also a natural audit trail. If your broker retains events (Kafka does this by default), you have a complete history of everything that happened. You can replay events to rebuild state, debug issues by examining the exact sequence of events, or spin up a new service that processes historical events to backfill its data.

Where Event-Driven Falls Short

After the order service publishes "order confirmed," there's a window where the inventory service hasn't yet processed the event. During that window, a concurrent request might read stale stock levels. If your use case requires "read your own writes" consistency, event-driven communication alone is not enough.

// The problem: order confirmed, but stock not yet decremented
async function handleCheckout(cart: Cart): Promise<Order> {
  const order = await createOrder(cart);
  await publishOrderConfirmed(order);

  // If another request checks stock RIGHT NOW,
  // it sees the old (pre-decrement) value.
  // The inventory consumer hasn't processed the event yet.
  return order;
}

Debugging also gets more complex. When something goes wrong in a synchronous call chain, you get a stack trace. When something goes wrong in an event-driven flow, you get a message in a dead-letter queue and a question: which producer sent this? When? What was the system state at that time? Distributed tracing helps, but correlating events across services is fundamentally harder than following a request through a call stack.

You can also have issues with ordering guarantees. Most brokers guarantee ordering within a partition (Kafka) or a queue, but not globally. If the order service publishes "order confirmed" and then "order cancelled," the inventory service might process the cancellation first if the events land on different partitions.

// Use a consistent partition key to guarantee ordering per entity
await producer.send({
  topic: "order.events",
  messages: [
    {
      // All events for the same order go to the same partition
      key: order.id,
      value: JSON.stringify(event),
    },
  ],
});

Keying messages by entity ID (order ID, customer ID) ensures events for the same entity are processed in order. Events for different entities can be processed in parallel.

Finally, your operations get more complex. Running a message broker isn't free. Kafka requires ZooKeeper (or KRaft), topic management, partition rebalancing, consumer group coordination, and monitoring for consumer lag. Managed services like Amazon MSK, Confluent Cloud, or Amazon SQS reduce this burden but add cost.

Handling Broker Failures

What happens when the broker is unavailable? If your service writes to the database and then publishes an event, a broker outage means the event is lost even though the database write succeeded.

These patterns help:

1. The Outbox Pattern

Instead of publishing directly to the broker, write the event to an "outbox" table in the same database transaction as your business data. A separate process (a poller or a change-data-capture connector like Debezium) reads the outbox table and publishes to the broker.

// Outbox pattern: write event to the database, not the broker
// db injected via dependency injection
async function confirmOrder(order: Order, db: Database): Promise<void> {
  await db.transaction(async (tx) => {
    // Business write and event write in the same transaction
    await tx.update("orders", { id: order.id, status: "confirmed" });
    await tx.insert("outbox", {
      id: crypto.randomUUID(),
      topic: "order.confirmed",
      key: order.id,
      payload: JSON.stringify({
        orderId: order.id,
        customerId: order.customerId,
        items: order.items,
        total: order.total,
      }),
      created_at: new Date(),
    });
  });
  // A separate relay process picks up outbox rows and publishes to Kafka
}

Because the event and the business data are written atomically, you never lose an event due to a broker outage. The relay process retries until the broker is back.

2. At-least-once delivery

Most brokers guarantee at-least-once delivery, meaning consumers may see the same event more than once (for example, after a rebalance or a retry). Your consumers must be idempotent: processing the same event twice should produce the same result as processing it once.

// Idempotent consumer: use the eventId to deduplicate
async function handleOrderConfirmed(event: EventEnvelope<OrderData>): Promise<void> {
  const alreadyProcessed = await db.query(
    "SELECT 1 FROM processed_events WHERE event_id = $1",
    [event.eventId]
  );

  if (alreadyProcessed.rows.length > 0) {
    logger.info("Duplicate event, skipping", { eventId: event.eventId });
    return;
  }

  await db.transaction(async (tx) => {
    await decrementStock(tx, event.data.items);
    await tx.insert("processed_events", {
      event_id: event.eventId,
      processed_at: new Date(),
    });
  });
}

The combination of the outbox pattern (producer side) and idempotent consumers (consumer side) gives you reliable event-driven communication even when the broker has intermittent failures.

The Five Trade-Off Dimensions

Choosing a communication pattern isn't about which is "best." It's about which trade-offs you can accept for each specific interaction. Here are the five dimensions that matter most.

1. Latency

Exact numbers depend on payload size, network hops, and infrastructure. The structural ordering is consistent: gRPC is fastest for synchronous calls, REST is close behind, and event-driven messaging trades latency for decoupling.

If the caller needs an immediate response (user-facing checkout, real-time search), use gRPC or REST. If the caller doesn't need the result right now (send email, update analytics), use events.

2. Coupling

Coupling has two dimensions: temporal (does the caller wait for the receiver?) and schema (do they share a contract?).

REST's loose typing is a double-edged sword. You can add fields to a JSON response without breaking consumers (additive changes are safe). But you can also accidentally remove a field, and the consumer fails at runtime instead of compile time.

gRPC's strict typing catches breaking changes at build time, but it means every schema change requires regenerating clients. For two services, this is trivial. For twenty services consuming the same proto, you need a coordination process.

Event-driven messaging decouples in time but still couples on the event schema. If the order.confirmed event changes its structure, every consumer must handle both the old and new format during the transition.

3. Schema Evolution

Schema evolution is how you change the contract between services without breaking existing consumers. This is where the three patterns diverge most sharply.

REST (JSON):

// Version 1: price as a number
{ "productId": "abc-123", "price": 49.99 }

// Version 2: price as an object (breaking change)
{ "productId": "abc-123", "price": { "amount": 49.99, "currency": "USD" } }

JSON has no built-in versioning. You manage it through one of three strategies:

Additive changes (new fields) are safe with any strategy. Structural changes (renaming fields, changing types) require explicit versioning — URL or header — so consumers can migrate at their own pace.

gRPC (Protocol Buffers):

// Protocol Buffers have built-in evolution rules
message StockResponse {
  string product_id = 1;
  int32 available = 2;
  int32 reserved = 3;
  // Field 4 was removed (never reuse field numbers)
  string warehouse_id = 5;       // New field: old clients ignore it
  optional string region = 6;    // Optional: old clients don't send it
}

Protocol Buffers handle evolution well by design. You can add new fields (old clients ignore them), deprecate fields (stop writing them, keep the number reserved), and use optional for fields that may not be present.

You can't rename fields, change field types, or reuse field numbers. These rules are enforced by the tooling.

Event-driven (Avro/JSON Schema):

For events, schema registries like Confluent Schema Registry enforce compatibility rules:

// Register a schema with backward compatibility
// New consumers can read old events, old consumers can read new events
const schema = {
  type: "record",
  name: "OrderConfirmed",
  fields: [
    { name: "orderId", type: "string" },
    { name: "customerId", type: "string" },
    { name: "total", type: "double" },
    // New field with default: backward compatible
    { name: "currency", type: "string", default: "USD" },
  ],
};

With a schema registry, producers can't publish events that violate the compatibility contract. This is the strongest governance model: the registry rejects incompatible schemas before they reach consumers.

4. Debugging and Observability

For event-driven systems, correlation IDs are essential:

// Always include a correlation ID in events
interface EventEnvelope<T> {
  eventId: string;
  eventType: string;
  correlationId: string; // Links related events across services
  causationId: string;   // The event that caused this one
  timestamp: string;
  source: string;
  data: T;
}

async function publishEvent<T extends { entityId: string }>(
  topic: string,
  type: string,
  data: T,
  correlationId: string,
  causationId?: string
): Promise<void> {
  const event: EventEnvelope<T> = {
    eventId: crypto.randomUUID(),
    eventType: type,
    correlationId,
    causationId: causationId ?? correlationId,
    timestamp: new Date().toISOString(),
    source: SERVICE_NAME,
    data,
  };

  await producer.send({
    topic,
    messages: [{ key: data.entityId, value: JSON.stringify(event) }],
  });
}

When investigating an issue, you search for the correlation ID across all services and reconstruct the full event chain. Without it, you're searching for a needle in a haystack.

5. Operational Complexity

REST has the lowest operational overhead. Every team knows how to run an HTTP server.

gRPC adds a build-time dependency (proto compilation) and requires teams to learn new tooling.

Event-driven adds a runtime dependency (the broker) that must be highly available because if the broker goes down, inter-service communication stops.

The Decision Framework

Use this framework when deciding how a specific pair of services should communicate. The answer is rarely one pattern for your entire system.

Does the caller need an immediate response?
├── Yes → Is this a public-facing or browser-accessible API?
│         ├── Yes → REST
│         └── No  → Is throughput or latency critical?
│                   ├── Yes → gRPC
│                   └── No  → REST (simpler, good enough)
└── No  → Can the caller tolerate eventual consistency?
          ├── No  → Use synchronous call (REST or gRPC) with async follow-up
          └── Yes → Does the event need to trigger multiple consumers?
                    ├── Yes → Event-driven messaging
                    └── No  → Is ordering critical?
                              ├── Yes → Event-driven with partition key
                              └── No  → Event-driven (or simple queue like SQS)

Some concrete examples:

Hybrid Architectures: Using All Three

Most production systems use a combination. Here's a pattern that works well:

┌──────────┐    REST     ┌──────────────┐    gRPC    ┌──────────────┐
│ Browser  │────────────▶│  API Gateway │───────────▶│ Order Service│
└──────────┘             └──────────────┘            └──────┬───────┘
                                                           │
                                                    publishes event
                                                           │
                                                           ▼
                                                    ┌─────────────┐
                                                    │    Kafka     │
                                                    └──────┬──────┘
                                          ┌────────────────┼────────────────┐
                                          ▼                ▼                ▼
                                   ┌────────────┐  ┌────────────┐  ┌────────────┐
                                   │ Inventory  │  │ Notification│  │ Analytics  │
                                   │  Service   │  │  Service    │  │  Service   │
                                   └────────────┘  └────────────┘  └────────────┘

• REST at the edge: the browser talks to the API gateway using standard HTTP. Cacheable, debuggable, universally supported.

• gRPC between the gateway and internal services: low latency, strong typing, efficient serialization.

• Event-driven for downstream reactions: the order service publishes an event, and multiple consumers react independently.

The Anti-Synchronous Trap

A common mistake is using synchronous calls (REST or gRPC) where events are a better fit. The symptom: a service that makes five synchronous calls during a single request, waiting for each to complete before responding to the caller.

// Anti-pattern: synchronous fan-out
async function confirmOrder(order: Order): Promise<void> {
  await inventoryService.decrementStock(order.items);    // 50ms
  await paymentService.capturePayment(order.paymentId);  // 200ms
  await notificationService.sendConfirmation(order);     // 100ms
  await analyticsService.recordConversion(order);        // 80ms
  await shippingService.createShipment(order);           // 150ms
  // Total: 580ms, and if any one fails, the order fails
}

Only the first two calls (inventory and payment) are critical to confirming the order. The rest are reactions that can happen asynchronously:

// Better: synchronous for critical path, events for reactions
async function confirmOrder(order: Order): Promise<void> {
  // Critical path: must succeed for the order to be valid
  await inventoryService.decrementStock(order.items);
  await paymentService.capturePayment(order.paymentId);

  // Non-critical: publish event, let consumers handle the rest
  await publishOrderConfirmed(order);
  // Total: 250ms, and notification/analytics/shipping failures
  // don't block the checkout
}

This is the same tiered approach from my designing resilient APIs article. Critical operations are synchronous. Non-critical reactions are event-driven. The caller responds faster, and downstream failures do not cascade.

Schema Governance at Scale

As your service count grows, schema management becomes a first-class concern. Here's a practical approach for each pattern.

REST: OpenAPI as the Contract

# openapi/inventory-service.yaml
openapi: "3.1.0"
info:
  title: Inventory Service
  version: "1.2.0"
paths:
  /api/v1/products/{productId}/stock:
    get:
      operationId: getStock
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Stock level for the product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StockResponse"
components:
  schemas:
    StockResponse:
      type: object
      required: [productId, available, reserved]
      properties:
        productId:
          type: string
        available:
          type: integer
        reserved:
          type: integer

Generate client SDKs from the OpenAPI spec using tools like openapi-typescript or openapi-generator. This gives you type safety without the build-time coupling of gRPC.

gRPC: Proto Registry

Store .proto files in a shared repository or a dedicated proto registry (Buf Schema Registry is a good option). Use Buf's breaking change detection in CI:

# Detects breaking changes before they merge
buf breaking --against ".git#branch=main"

This command requires a buf.yaml configuration file at the root of your proto directory. The file defines your module name and any lint or breaking change rules. See the Buf documentation for setup details.

This fails your pull request if you rename a field, change a type, or reuse a field number. Non-breaking changes (adding fields, adding services) pass through.

Events: Schema Registry with Compatibility Modes

For event-driven systems, a schema registry enforces compatibility at publish time. Confluent Schema Registry supports four modes:

Use FULL compatibility for production topics. It ensures that any consumer, regardless of which schema version it was built against, can read any event on the topic.

Conclusion

In this article, you learned the core mechanics of REST, gRPC, and event-driven messaging, the five trade-off dimensions that matter when choosing between them (latency, coupling, schema evolution, debugging, and operational complexity), and a decision framework for matching patterns to specific service interactions.

The key takeaways:

1. REST for the edge: Browser clients, public APIs, simple CRUD. Cacheable, debuggable, universally supported.

2. gRPC for internal hot paths: High-throughput service-to-service calls where latency matters and both sides are under your control.

3. Events for reactions: When the producer shouldn't wait, when multiple consumers need the same signal, or when temporal decoupling prevents cascading failures.

4. Use all three: Most production systems combine patterns. REST at the boundary, gRPC internally, events for async workflows.

5. Schema governance scales the system: OpenAPI for REST, proto registries for gRPC, schema registries for events. Without governance, schema changes become the primary source of production incidents.

The right communication pattern isn't a global decision. It's a per-interaction decision, made deliberately, based on which trade-offs you can accept for that specific data flow.

In this article, we’ll walk step by step through how performance issues arise in Django REST APIs, how to see them clearly using profiling tools, and how to fix them using query optimization, caching, pagination, and basic scaling strategies.

This article will be most useful for developers who already understand Django, the Django REST Framework, and REST concepts, but are new to performance optimization.

What we’ll cover:

• Why Django REST APIs Become Slow

• Profiling: Finding the Real Bottlenecks

• Logging SQL Queries

• Summary and Next Steps

Why Django REST APIs Become Slow

Before optimizing anything, it’s important to understand why APIs become slow in the first place.

Most performance issues in Django REST APIs come from three main sources:

1. Too many database queries

2. Doing expensive work repeatedly

3. Returning more data than necessary

Django is fast by default, but it does exactly what you ask it to do. If your API endpoint triggers 300 database queries, Django will happily run all 300.

Now let’s look at some common causes of performance issues in Django REST APIs.

1. N+1 Query Problems in Serializers

This happens when you loop over objects and access related fields, causing a separate query for each object.

# models.py
class Author(models.Model):
    name = models.CharField(max_length=100)

class Post(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

# views.py (naive approach)
posts = Post.objects.all()
for post in posts:
    # This triggers a query per post to fetch the author
    print(post.author.name)

If you have 100 posts, this runs 101 queries: 1 for posts and 100 for authors. Django lazily loads related objects by default, so without intervention, your API performs repetitive database work that slows response times.

2. Fetching Related Objects Inefficiently

# Naive queryset fetching all related objects separately
posts = Post.objects.all()
authors = [post.author for post in posts]  # triggers extra queries per post

Each access to post.author triggers a new query. Even though you already fetched all posts, Django lazily loads related objects by default. This creates many extra queries, slowing down your API.

3. Serializing Large Datasets Without Pagination

Returning large query sets all at once can slow down your API and increase memory usage.

# views.py
from rest_framework.response import Response
from rest_framework.decorators import api_view
from .models import Post
from .serializers import PostSerializer

@api_view(['GET'])
def all_posts(request):
    posts = Post.objects.all()  # retrieves all posts at once
    serializer = PostSerializer(posts, many=True)
    return Response(serializer.data)

If your database has thousands of posts, this endpoint fetches everything in memory, serializes it, and sends it over the network. It’s slow and can crash under load. Later, we’ll learn to paginate results efficiently.

4. Recomputing Expensive Work Repeatedly

Some endpoints calculate the same values on every request instead of caching or precomputing.

def expensive_view(request):
    # Simulate expensive computation
    result = sum([i**2 for i in range(1000000)])
    return JsonResponse({"result": result})

Even if the data doesn’t change often, this computation happens on every request, consuming CPU time unnecessarily.

Performance optimization is about reducing unnecessary work.

At this point, it might be tempting to jump straight into fixes like caching responses or optimizing database queries. But doing that without evidence often leads to wasted effort or even new problems.

Before changing anything, you need to understand where your API is actually spending time. Is it the database? Is it serialization? Is it Python code running repeatedly on every request? This is where profiling becomes essential.

Profiling: Finding the Real Bottlenecks

Optimizing without profiling is guessing. Profiling helps you answer one question:

Where is my API actually spending time?

In practice, profiling means observing an API while it runs and collecting data about what it’s doing. This includes how many database queries are executed, how long those queries take, and how much time is spent in Python code, such as serializers or business logic.

By profiling first, you avoid making assumptions and can focus on fixing the parts of your API that are truly slowing things down.

Measuring Query Count in a View

During development, Django keeps track of all executed queries. You can inspect them directly:

from django.db import connection
from rest_framework.decorators import api_view
from rest_framework.response import Response
from .models import Post
from .serializers import PostSerializer

@api_view(["GET"])
def post_list(request):
    posts = Post.objects.all()
    serializer = PostSerializer(posts, many=True)

    response = Response(serializer.data)

    print(f"Total queries executed: {len(connection.queries)}")

    return response

If this prints 101 queries for 100 posts, you likely have an N+1 problem. This simple check confirms whether the database layer is the bottleneck.

One of the easiest ways to profile Django applications during development is by using tools that expose this information directly while requests are being processed.

Using the Django Debug Toolbar

The Django Debug Toolbar is one of the simplest ways to understand performance during development. It acts as a lightweight profiling tool that shows what happens behind the scenes when a request is handled.

It shows you:

• How many SQL queries were executed

• How long each query took

• whether queries are duplicated

• Which parts of the request lifecycle are slow

How to Install and Enable the Django Debug Toolbar

First, install it:

pip install django-debug-toolbar

In settings.py:

INSTALLED_APPS = [
    ...
    "debug_toolbar",
]

MIDDLEWARE = [
    ...
    "debug_toolbar.middleware.DebugToolbarMiddleware",
]

INTERNAL_IPS = [
    "127.0.0.1",
]

In urls.py:

import debug_toolbar
from django.urls import path, include

urlpatterns = [
    ...
    path("__debug__/", include(debug_toolbar.urls)),
]

When you load an endpoint in the browser during development, the toolbar displays total SQL queries, execution time, and duplicate queries. This makes inefficiencies immediately visible.

When you load an API endpoint and see 150 SQL queries for a single request, that’s a strong signal that something is wrong, often an N+1 query problem or inefficient serializer behavior.

Logging SQL Queries

Django allows you to log all executed SQL queries. This is especially useful when debugging API views.

Seeing the raw SQL makes inefficiencies obvious, such as repeated SELECT statements for the same table.

How to Enable SQL Query Logging

You can configure Django to log all SQL queries in settings.py:

LOGGING = {
    "version": 1,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "loggers": {
        "django.db.backends": {
            "handlers": ["console"],
            "level": "DEBUG",
        },
    },
}

With this configuration, every SQL query will be printed to the console when your API runs. Repeated SELECT statements or unexpected queries become obvious.

Profiling API Response Time

Database queries are only one part of API performance. Beyond queries, it’s also important to measure the total response time of an endpoint.

Profiling response time helps you understand whether delays are caused by database access or by other parts of the request lifecycle. For example, if an endpoint takes 1.2 seconds to respond but only 50 milliseconds are spent on database queries, the bottleneck is likely in serialization, business logic, or repeated computations in Python.

By comparing query time and total response time, profiling helps you identify what to fix first instead of optimizing the wrong layer of the system.

How to Measure Total Response Time

import time
from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(["GET"])
def example_view(request):
    start_time = time.time()

    # Simulate work
    data = {"message": "Hello world"}

    response = Response(data)

    end_time = time.time()
    print(f"Response time: {end_time - start_time:.4f} seconds")

    return response

If database queries are fast but the total response time is high, the bottleneck may be serialization or expensive Python logic.

Once you’ve identified that database access is a significant contributor to slow response times, the next step is to look more closely at how Django retrieves related data.

SQL Query Optimization in Django REST APIs

One of the most common reasons Django REST APIs become slow is inefficient access to related objects. This often manifests as the N+1 query problem, where fetching related objects triggers a separate database query for each item. Identifying and fixing this problem can significantly reduce the number of queries and improve API performance.

Understanding the N+1 Query Problem

Consider a simple example:

• You fetch a list of posts

• Each post has an author

• For every post, Django fetches the author separately

If you have 100 posts, this results in 101 queries: 1 for the posts and 100 for the authors. This happens because Django lazily loads related objects by default. Without intervention, your API performs repetitive database work that slows down response times.

Solving the Problem with select_related and prefetch_related

Django provides built-in tools to control how related objects are loaded efficiently: select_related and prefetch_related.

1. Using select_related

select_related is designed for foreign key and one-to-one relationships. It performs an SQL join and retrieves related objects in a single query.

Use it when:

• You know you will access related objects

• The relationship is one-to-one or many-to-one

posts = Post.objects.select_related("author")

for post in posts:
    print(post.author.name)  # No additional queries

This performs a SQL JOIN and retrieves posts and authors in a single query, eliminating the N+1 problem.

It reduces multiple queries into just one, avoiding repeated database hits.

2. Using prefetch_related

prefetch_related is used for many-to-many and reverse foreign key relationships. It performs separate queries for each related table but combines the results in Python.

Use it when:

• A SQL join would produce too much duplicated data

• You are dealing with collections of related objects

Example: How to Optimize a Many-to-Many Relationship

Consider a blog application where posts can have multiple tags:

# models.py
class Tag(models.Model):
    name = models.CharField(max_length=50)

class Post(models.Model):
    title = models.CharField(max_length=200)
    tags = models.ManyToManyField(Tag)

Now imagine fetching posts and accessing their tags:

posts = Post.objects.all()

for post in posts:
    print(post.tags.all())  # Triggers additional queries

If you have 100 posts, Django may execute:

• 1 query to fetch posts

• 1 query per post to fetch related tags

This results in many unnecessary database hits.

You can optimize this using prefetch_related:

posts = Post.objects.prefetch_related("tags")

for post in posts:
    print(post.tags.all())  # Uses prefetched data

With this approach, Django performs one query for posts and one query for all related tags. It then matches them in Python, eliminating repeated database queries.

Together, these tools allow you to optimize your queries and eliminate the N+1 problem efficiently.

Common Beginner Mistakes

Even after applying these optimizations, it’s easy to make mistakes. Watch out for:

• Forgetting that serializers can trigger additional queries

• Using select_related on many-to-many relationships

• Assuming Django automatically optimizes queries

• Not checking the query count after adding serializers

Paying attention to these pitfalls ensures your API remains fast and scalable.

Caching in Django REST APIs

Even after optimizing database queries, API performance can still suffer if the same computations or database lookups are performed repeatedly. This is where caching comes in. Caching is a technique for storing the results of expensive operations so they can be retrieved more quickly the next time they are needed.

At its core, caching exists because computers have multiple layers of memory with different speeds:

• CPU registers (fastest)

• L1, L2, L3 caches

• Main memory (RAM)

• SSD storage

• HDD storage (slowest)

Each layer trades speed for size: the closer the data is to the CPU, the faster it can be accessed. Software systems use the same principle; by storing frequently accessed data in a “closer” or faster location, applications can respond more quickly.

Cache Eviction

Caches are limited in size, so when a cache is full, some data must be removed to make room for new data. This process is called cache eviction.

Common eviction strategies include:

• Least Recently Used (LRU): removes the data that hasn’t been accessed for the longest time

• Random Replacement: removes a random item from the cache

The goal is to keep the data that is most likely to be requested again while freeing space for new data. Understanding this helps developers use caching effectively.

Caching in Application Architectures

Caching exists at several levels in modern software systems:

• Client-side caching: Web browsers cache HTTP responses to reduce the need for repeated network requests. This is controlled with HTTP headers like Cache-Control.

• CDN caching: Content Delivery Networks store static assets closer to users, reducing latency and server load.

• Backend caching: Backend services cache results from database queries, computed values, or API responses. This is where Django caching is most commonly applied.

By applying caching strategically at the backend, APIs can serve data faster while reducing computation and database load.

Caching in Django

Django provides a flexible caching framework that supports multiple backends, including in-memory, file-based, database-backed, and third-party stores like Redis. The main types of caching in Django are:

1. Per-view caching: caches the entire output of a view. Ideal for endpoints where responses rarely change.

    from django.views.decorators.cache import cache_page
   
    @cache_page(60 * 15)  # cache for 15 minutes
    def my_view(request):
   

   2. Template fragment caching: caches specific parts of a template to avoid repeated rendering.

   3. Low-level caching: gives full control over what is cached and for how long, making it ideal for API responses.

By combining these approaches, you can reduce repeated work in your API, lower database load, and speed up response times.

When to Use Redis

While Django’s built-in caching backends are sufficient for many projects, high-traffic APIs often require a shared, in-memory cache. This is where Redis excels. Redis is designed for fast access, low latency, and can handle frequent reads across multiple servers.

You should consider using Redis when:

• Data is read frequently but changes infrequently

• Low latency is important for API responses

• You need cache expiration and eviction policies

• You want a shared cache across multiple servers or services

Redis is particularly effective for API endpoints that serve the same data to many users, such as frequently accessed lists or computed results.

Common Beginner Mistakes

Caching is powerful, but it’s easy to misuse. Some common pitfalls include:

• Caching everything blindly: not all data benefits from caching

• Forgetting cache invalidation: stale data can lead to incorrect responses

• Using cache where query optimization would suffice: sometimes optimizing database queries is a better solution than caching.

Remember: caching should complement good database design, not replace it.

Pagination and Limiting Expensive Datasets

Even with caching, returning large datasets in a single request can slow down your API and increase memory usage. Pagination is a simple and effective way to limit the amount of data returned at once.

Pagination helps by reducing:

• Database load

• Memory usage

• Serialization time

• Network transfer size

Django REST Framework provides built-in pagination classes that make it easy to paginate endpoints. As a rule of thumb, always paginate list endpoints unless there is a strong reason not to.

Load Testing and Measuring Improvement

Optimizations are only meaningful if you can measure their impact. Load testing simulates multiple users accessing your API simultaneously, helping you answer key questions:

• How many requests per second can my API handle?

• Where does the API start to break under load?

• Did caching, query optimization, and pagination actually improve performance?

By running load tests before and after optimization, you can validate that your changes have the desired effect and avoid optimizing the wrong parts of your system.

Summary and Next Steps

Optimizing Django REST APIs isn’t about chasing every tiny micro-optimization. It’s about reducing unnecessary work and focusing on the parts of your API that actually slow down performance.

Key Takeaways

• Profile before optimizing: Identify the real bottlenecks before making changes.

• Reduce database queries: Use techniques like select_related, prefetch_related, and avoid N+1 queries.

• Cache frequently accessed data: Use Django caching and Redis to reduce repeated computations.

• Paginate large datasets: Limit memory usage and network load by returning data in chunks.

• Measure performance changes: Always verify that your optimizations have a real impact.

Next Steps for Your APIs

1. Add profiling to your existing APIs to understand where time is spent.

2. Identify one slow endpoint and focus on optimizing it first.

3. Optimize database queries using Django ORM best practices.

4. Introduce caching carefully; avoid caching everything blindly.

5. Measure the results with load testing and performance metrics.

Remember: Performance optimization is not a one-time task. It’s a habit built by continuously observing how your system works, testing improvements, and applying changes where they make the most impact.

Read More

1. DRF Performance

2. Django ORM Optimization

3. Understanding N+1 queries

The answer often lies in a powerful, yet often invisible, technology: Web Services.

Think of the internet as a bustling city. Different buildings (applications) have different functions and are built by different architects (developers) using different materials (programming languages and platforms).

So how do these distinct buildings interact efficiently? They need standardized roads, delivery services, and communication protocols. Web services are the digital equivalent of these crucial city infrastructure components.

In this article, you’ll learn what Web Services are and why they’re important. You’ll also learn about different types of Web Services, like Simple Object Access Protocol (SOAP) and Representational State Transfer (REST), and when to use each one. We’ll wrap up with some examples so you can see them in action.

Table of Contents:

• What Exactly is a Web Service?

• Why are Web Services So Important?

• Types of Web Services

• Comparing and Contrasting SOAP and REST Web Services

• What if one service uses SOAP and the other uses REST?

• Web Services in Action: Examples

• Final Thoughts:

What Exactly is a Web Service?

At its core, a web service is a standardized way for different software applications to communicate with each other over a network – typically the internet. It allows application 'A' (running on, say, a Windows server using Java) to request information or trigger an action from application 'B' (running on a Linux machine using Python), without either application needing to know the intricate internal details of the other.

Here’s how they make this happen:

1. Network accessibility: They operate over standard web protocols like HTTP/HTTPS.

2. Standardized messaging: They use common data formats like XML (Extensible Markup Language) or JSON (JavaScript Object Notation) to structure the data being exchanged.

3. Interface description: They often come with a "contract" or description (like WSDL for SOAP services or OpenAPI/Swagger definitions for REST APIs) that tells other applications how to interact with them – what functions are available and what data format to expect.

Why are Web Services So Important?

The rise of web services has revolutionized software development and the internet itself. They’re important for several key reasons.

First, interoperability. This is the biggest win. Web services break down technology silos. An application written in C# can seamlessly talk to one written in Ruby, as long as they agree on the web service protocol and data format.

Next, reusability. A company can build a specific function (like processing payments or checking stock inventory) as a web service once. Then, multiple internal or external applications can reuse that same service, saving significant development time and effort.

Also, loose coupling. Applications using a web service don't need to be tightly bound to it. The service provider can update the internal workings of the service without breaking the applications that consume it, as long as the communication interface remains consistent. This makes systems more flexible and easier to maintain.

And finally, platform independence. Because they rely on web standards, web services work across different operating systems and hardware.

Types of Web Services

Web services can be broadly categorized into different types, each with its own characteristics and suitable use cases. The two most prominent types are SOAP and REST. Other types include XML-RPC, UDDI, GraphQL , and gRPC.

SOAP (Simple Object Access Protocol)

SOAP web services are often used in enterprise-level applications requiring high security and transactional integrity, like banking, finance, and telecommunications.

• Protocol: SOAP (Simple Object Access Protocol) is a formal protocol with strict rules defined by the W3C that relies on XML for message format and usually HTTP/HTTPS for message negotiation and transmission.

• Structure: SOAP messages are composed of an envelope, header, and body:

  • Envelope: Defines the start and end of the message, and includes namespaces for components.

  • Header: Contains optional attributes for message routing and quality of service.

  • Body: Contains the actual call and response information, wrapped in XML.

• Communication: SOAP is protocol-driven and uses WSDL (Web Services Description Language) to describe the services offered and how to interact with them.

• Use cases: A SOAP request might be used to call a banking service to check an account balance. The response will be strictly formatted as XML, fulfilling the service’s requirements.

Example: a currency conversion web service

SOAP Request (XML)

POST /CurrencyService.asmx HTTP/1.1
Host: www.example.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.example.com/ConvertCurrency"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ConvertCurrency xmlns="http://www.example.com/">
      <FromCurrency>USD</FromCurrency>
      <ToCurrency>EUR</ToCurrency>
      <Amount>100</Amount>
    </ConvertCurrency>
  </soap:Body>
</soap:Envelope>

SOAP Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ConvertCurrencyResponse xmlns="http://www.example.com/">
      <ConvertCurrencyResult>92.5</ConvertCurrencyResult>
    </ConvertCurrencyResponse>
  </soap:Body>
</soap:Envelope>

REST (Representational State Transfer)

REST web services are often used for building APIs that let apps perform CRUD operations on resources, like fetching data from a database or interacting with other services. REST is especially popular in web development because it’s relatively simplicity, quite scalable, and uses standard HTTP methods (GET, POST, PUT, DELETE).

• Architecture: REST (Representational State Transfer) is an architectural style rather than a protocol. It relies on standard HTTP methods like GET, POST, PUT, DELETE, to interact with resources.

• Data Exchange: REST usually exchanges data in JSON or XML format. JSON is more common due to its lightweight nature.

• Structure: REST doesn’t have a WSDL-like formal contract. Instead, resources are identified via URLs, and HTTP status codes indicate the result of requests.

• Generally considered simpler, more flexible, and scalable, making it extremely popular for web and mobile applications (these are often referred to as RESTful APIs).

• Use cases: A REST API might be used to retrieve data about a book in a bookstore application, using a simple HTTP GET request.

Example: a currency conversion web service

REST Request

GET /api/convert?from=USD&to=EUR&amount=100 HTTP/1.1
Host: www.example.com

OR

Using POST:

POST /api/convert HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}

REST Response (JSON)

{
  "from": "USD",
  "to": "EUR",
  "amount": 100,
  "result": 92.5
}

In modern web development, particularly for public APIs and microservices, REST (especially using JSON over HTTPS) has become the most popular and often preferred approach due to its simplicity and performance benefits. But SOAP remains relevant and necessary in specific enterprise contexts.

Comparing and Contrasting SOAP and REST Web Services

What if One Service Uses SOAP and the Other Uses REST?

By default, SOAP and REST are not directly compatible because SOAP uses XML with a strict message format, and REST uses HTTP methods and often JSON payloads.

So, they can’t communicate to each other directly without some integration layer or adapter. Here’s how you can handle this situation:

• Use intermediary services: You can use a middleware or API gateway that can handle both SOAP and REST protocols. These services can translate SOAP requests into REST requests and vice-versa.

• Use adapters: Write adapters that convert SOAP XML messages to REST JSON requests. Essentially, a piece of software acts as a translator between the two formats.

• Direct integration: While complex, this involves custom software development where the SOAP service can be manually configured to invoke REST endpoints.

• Use an ESB (Enterprise Service Bus): An ESB can integrate diverse applications and data formats within enterprise architecture, acting as a mediator that understands both SOAP and REST.

• Expose a hybrid API: Some modern APIs expose both SOAP and REST endpoints for the same backend logic.

  • Example: Amazon Web Services (AWS) used to have SOAP and REST APIs for some services. This lets clients choose which protocol they prefer.

Web Services in Action: Examples

• Weather apps: Your phone app likely calls a weather web service, sending your location and receiving back forecast data.

• Online payments: When you buy something online, the e-commerce site often communicates with a payment gateway's web service to securely process your credit card information.

• Travel aggregators: Sites like MakeMyTrip or Kayak use web services provided by airlines and hotels to fetch real-time flight and room availability and prices.

• Social logins: "Login with Google" or "Login with Facebook" buttons use authentication web services (often based on OAuth) to verify your identity without you needing a separate password for that site.

Final Thoughts

Web services have fundamentally transformed how applications interact and exchange data over networks. Their ability to facilitate interoperability, reusability, and scalability has made them indispensable in modern software development and system integration.

While SOAP and REST represent the two dominant styles, each with its strengths and weaknesses, their choice often depends on specific project requirements, particularly concerning security, performance, and complexity.

Understanding the core functionalities, underlying technologies, common use cases, and security considerations of web services provides a solid foundation for navigating the landscape of distributed computing.

REST works so well because it speaks the web’s native language. It uses familiar HTTP methods like GET, POST, PUT, and DELETE, treats data as resources, and follows clear conventions. All this makes it easy to understand, quick to implement, and widely supported, which is why most modern web APIs follow REST principles.

In this article, I will explore REST concepts and core principles while we build a simple Express application step by step. You will learn:

• What is REST architecture, and what are its advantages in web development?

• The core REST principles (statelessness, resources, HTTP methods, and so on)

• How to implement these principles in a real Express.js app

• Best practices for designing clean and consistent APIs

Here’s what we will cover:

• What is REST

• Why use REST?

• Core Principles of REST Architecture

• Build a Simple Express App

  • What is Express?

  • Set Up the Express App

  • Build RESTful Resources

  • Middlewares

  • Test your Express App

• Bad REST Practices to Avoid

• Conclusion

What is REST?

Representational State Transfer (REST) is a style of designing networked applications that emphasises a stateless client-server communication model centred around resources. Think of it like ordering at a restaurant: each time you ask for something, you have to tell the waiter exactly what you want, and they don't remember your previous orders.

RESTful APIs treat data as resources, each accessible through a unique web address (URI). Then, it leverages the standard actions defined by HTTP methods – POST to create new resources, GET to retrieve them, PUT to modify existing ones, and DELETE to remove them – providing a consistent and well-understood way to interact with data over the internet.

Why Use REST?

REST architectural principles offer a compelling set of advantages that contribute to building robust, scalable, and maintainable web services. Below are some of the key benefits that make REST a preferred choice for modern web development:

• Simplicity and familiarity: REST leverages standard HTTP, which is already well-understood by developers and infrastructure.

• Scalability: The stateless nature of REST allows for easy scaling of both client and server components independently.

• Flexibility and interoperability: RESTful APIs can be consumed by a wide variety of clients, regardless of the technology stack.

• Cacheability: REST's design supports caching mechanisms, leading to improved performance and reduced server load.

• Loose coupling: The client and server are independent, allowing for changes on either side without necessarily affecting the other.

• Visibility and monitoring: The straightforward nature of HTTP requests and responses makes it easier to monitor and debug interactions.

Core Principles of REST Architecture

REST (Representational State Transfer) is built on a few simple principles that make APIs easy to understand and use. Here’s a quick breakdown of the key ones:

Statelesness

Every request from the client to the server must contain all the information needed to process it. The server doesn’t store anything about the client between requests – no session, no memory of previous actions.

Example: If a user sends GET /movies/1, the server returns the movie data without needing to know whether the user is logged in or what they requested before.

This makes APIs easier to scale, since each request can be handled independently.

Resource and URIs

In REST, everything you work with is considered a resource – users, products, and so on. Each resource should be accessible via a unique, meaningful URL.

Example:

• /movies – a collection of movie resources

• /movies/42 – a specific movie with ID 42

Resources are treated like nouns. Actions are determined by the HTTP method used.

Standard HTTP Methods

REST takes full advantage of HTTP methods to describe what action you’re taking on a resource:

• GET – retrieve data

• POST – create a new resource

• PUT – update or replace a resource

• PATCH – partially update a resource

• DELETE – remove a resource

Example: To delete a movie, you’d send a DELETE request to /movies/42. That’s clear, consistent, and intuitive.

Uniform Interface

REST enforces a consistent structure for communication between client and server. This means all REST APIs should behave similarly, no matter who built them. It includes:

• Using URIs to identify resources

• Using standard HTTP methods

• Representing data in formats like JSON or XML

• Self-descriptive messages (for example, proper status codes and headers)

This consistency makes it easier for developers to understand and integrate with RESTful APIs.

Cacheability

Servers should label responses as cacheable (stored to be retrieved later) or not, so clients can reuse responses when appropriate. This reduces unnecessary server load and improves performance.

Example: A GET /movies response can be cached for 5 minutes if the data doesn’t change frequently. That means fewer repeated calls for the same info.

Client-Server Separation

The client (frontend) and server (backend) operate independently. The client just needs to know how to communicate with the API – it doesn’t care how the server handles data, and vice versa.

This separation allows teams to develop and scale frontend and backend systems separately.

The principles above help create APIs that are scalable, predictable, and easy to work with.

How to Build a Simple Express App

What is Express?

Express.js is a lightweight and flexible Node.js web application framework. Built on top of Node.js, it provides a robust set of features for building single-page, multi-page, and hybrid web applications and APIs. Think of it as a helpful toolkit that streamlines the process of setting up and managing web servers and routing requests.

In this exercise, you will be building an Express app that will:

1. Handle a simple in-memory collection of movies as a RESTful resource

2. Support basic CRUD operations using the appropriate HTTP methods (GET, POST, PUT, DELETE)

3. Parse incoming JSON requests using built-in middleware

4. Use a custom middleware function to validate movie input before creating or updating entries

5. Send clear and meaningful responses based on the outcome of each request

By the end, you’ll have a working API that follows REST principles and can be tested using a tool like Thunder Client or Postman.

Set Up the Express App

To get the most out of this exercise, there are a few tools and concepts you should already be familiar with. Since we’re focusing on REST principles and how to apply them using Express, we won’t dive deep into the basics of these prerequisites. Make sure you’re comfortable with the following:

• Node.js

• Npm

• Thunderclient extension

• Basic JavaScript

With that, let’s get started.

Open your command prompt and create a new directory (folder):

mkdir express-app

Navigate into your new directory:

cd express-app

Initialize an npm project:

npm init -y

Install the Express package in your project:

npm install express

Now, open your directory in your code editor with the following command:

code .

Create a new file, server.js, and set up your Express app in that file:

const express = require('express');
const app = express();
app.use(express.json());

app.listen(8000, () => console.log('Server running on port 8000'));

This snippet above sets up a basic Express server. It starts by importing the Express library you installed, enables JSON parsing for incoming requests (so we can work with request bodies), and listens on port 3000. It’s ready to handle RESTful routes like GET, POST, PUT, and DELETE as we build out our API.

To start your server, go back to your command prompt and type in this command:

node server.js

You should see this logged in your command prompt:

Build RESTful Resources

With our Express app set up, let’s build out the /movies resource using RESTful routes. We'll treat each movie as a resource and use HTTP methods to define what we want to do – retrieve, add, update, or delete movies. For simplicity, we'll store the movies in an in-memory array.

Here is the full set of routes. Add it in your server.js file just under your app.use(express.json()); line:

// In-memory database (for demonstration purposes)
// In a real application, you would use a database like MongoDB or PostgreSQL
const movies = [];

// Get all movies
app.get('/movies', (req, res) => {
  res.json(movies);
  console.log(movies);
});

// Get a particular movie by ID
app.get('/movies/:id', (req, res) => {
  const movie = movies.find(m => m.id === parseInt(req.params.id));
  if (!movie) return res.status(404).send('Movie not found');
  res.json(movie);
});

// Add a new movie
app.post('/movies', (req, res) => {
  const movie = {
    id: movies.length + 1,
    title: req.body.title,
    genre: req.body.genre,
    year: req.body.year
  };
  movies.push(movie);
  res.status(201).json(movie);
});

// Update a movie
app.put('/movies/:id', (req, res) => {
  const movie = movies.find(m => m.id === parseInt(req.params.id));
  if (!movie) return res.status(404).send('Movie not found');

  movie.title = req.body.title;
  movie.genre = req.body.genre;
  movie.year = req.body.year;

  res.json(movie);
});

// Delete a movie
app.delete('/movies/:id', (req, res) => {
  const movieIndex = movies.findIndex(m => m.id === parseInt(req.params.id));
  if (movieIndex === -1) return res.status(404).send('Movie not found');

  const deletedMovie = movies.splice(movieIndex, 1);
  res.json(deletedMovie);
});

The code above defines a complete set of RESTful routes for managing a movies resource using Express.

It begins with an in-memory array, movies, which acts as our temporary data store. The GET /movies route returns all books, while GET /movies/:id looks up a book by its ID using Array.find(), returning a 404 status if it's not found. The POST /movies route accepts JSON input, creates a new book with an auto-incremented ID, and adds it to the array, returning the new resource with a 201 Created status.

The PUT /movies/:id route handles full updates. It first finds the book, and if found, updates its title , genre, and year with the new values from the request body. The DELETE /movies/:id route removes a movie by finding its index in the array and using splice(). If the movie doesn't exist, both PUT and DELETE return a 404 error.

These routes demonstrate idempotency – that is, sending the same PUT or DELETE request multiple times will have the same effect as sending it once, a key REST principle. Each route also returns appropriate HTTP status codes and JSON responses, following REST conventions closely.

Each route follows a REST principle:

• Uses nouns for endpoints (/movies)

• Uses standard HTTP methods to express actions

• Ensure idempotency where appropriate (PUT, DELETE)

• Return appropriate status codes and messages

This structure keeps your API predictable and easy to use – exactly what REST is all about.

Middlewares

In RESTful APIs built with frameworks like Express, middleware plays a key role in maintaining clean, modular, and consistent request handling.

Middlewares are functions that sit in the middle of the request-response cycle in an Express app. When a client sends a request, middleware functions have access to the req (request), res (response), and next objects. They can inspect, modify, or act on the request before it reaches the route handler or even terminate the response early.

You have already seen a middleware here: app.use(express.json());. This is a global middleware that is used for parsing JSON. We will be creating a custom middleware for validating input for our POST and PUT requests.

Add the following code in your server.js file just before your routes:

// Middleware for simple validation
const validateMovie = (req, res, next) => {
  if (!req.body.title || !req.body.genre || !req.body.year) {
      return res.status(400).send('Title, genre, and year are required');
  }
  next();
};

This middleware function, validateMovie, performs basic validation on incoming requests before they reach the route handler. It checks if the title, genre, and year fields are present in the request body. If any of these fields are missing, it immediately responds with a 400 Bad Request status and an error message. If all required fields are provided, it calls next() to pass control to the next middleware or route. This keeps validation logic separate and reusable, helping maintain clean and RESTful route handlers.

To use this middleware, pass it as an argument in your POST and PUT routes, for example example:

app.post('/movies', validateMovie, (req, res) => {
  const movie = {
    id: movies.length + 1,
    title: req.body.title,
    genre: req.body.genre,
    year: req.body.year
  };
  movies.push(movie);
  res.status(201).json(movie);
});

Test Your Express App

To test the changes you have made, you need to restart your server. Go to your command prompt and press CTRL + C (for Windows) or Command + . (for MacOS). Input the start command like before to start the server again.

For this exercise, you will be testing the endpoints with the Thunder Client extension on VSCode. Thunder Client is a lightweight REST API extension for VSCode. With Thunder Client, you can your REST API routes and endpoints directly in VSCode.

To download Thunder Client, click on the Extension icon on the taskbar on your left and search “Thunder Client”. Then click Install:

After installation, you'll see the Thunder Client icon appear in your sidebar below the Extensions icon. Click it, then hit New Request to open a new tab. The request tab will open with a clean layout, ready for you to send and test API calls:

To start testing your API, set the request method (GET, POST, PUT, or DELETE) from the dropdown and enter the appropriate route, like http://localhost:3000/movies. For GET requests, just hit Send and you should see a response, in this case, an empty array []. To get a specific movie, you include an ID (for example, /movies/1).

For POST, PUT, and DELETE requests, switch to the Body tab and select the JSON format. Then provide the data you want to send:

• POST /movies: Add a new movie with {"title": "Movie Title", "genre": "Genre Name", "year": 0000}.

• PUT /movies/1: Update an existing movie with the same JSON structure.

• DELETE /movies/1: Remove a movie by its ID — no body is needed.

After sending each request, Thunder Client will display the response body, headers, and status code. Example:

Bad REST Practices to Avoid

When building REST APIs, aside from using the right HTTP methods, you also have to consider avoiding practices that break the core principles of REST. These bad practices can make your API harder to use, less predictable, or even misleading.

Here are some common REST bad practices and how to avoid them:

Using verbs in endpoints

Avoid routes like /getMovies or /createMovie. RESTful APIs rely on HTTP methods to express actions, so use nouns for endpoints and let methods do the talking — for example, use GET /movies to retrieve movies and POST /movie to create one.

Ignoring HTTP status codes

Returning 200 OK for every response, even errors, breaks REST conventions. Use the appropriate status codes: 201 Created for successful POSTs, 404 Not Found when a resource doesn’t exist, and 400 Bad Request for validation issues. This helps clients interpret responses correctly.

Overloading a single endpoint

Avoid writing one endpoint that changes behaviour based on the request body or headers. Each route should clearly map to a resource and method, like GET /movies/1 to fetch, and DELETE /movies/1 to remove, making the API predictable and easy to follow.

Not being idempotent where expected

PUT and DELETE should be idempotent, meaning repeated requests should have the same effect. If calling DELETE /movies/1 twice causes an error or unexpected behaviour, that’s a red flag. Design your handlers to handle these cases gracefully.

Exposing internal logic or database structure

Don’t leak internal details like database table names or query logic in your route naming (/api/movie_table_data). Keep your URIs clean, abstracted, and centred around the actual resource, like /movies.

Avoiding these practices not only keeps your API RESTful but also improves developer experience, consistency, and long-term maintainability.

Conclusion

You have explored the core ideas behind REST and put them into practice by building and testing a real Express API. This hands-on approach should help bridge the gap between theory and real-world application.

Along the way, you learned how REST treats resources, how to write clean and predictable routes, and why these principles matter when designing APIs that are easy to use and maintain.

Here’s a quick recap of what you’ve built and learned:

• Defined what REST is and why it’s widely used in web development

• Explored core REST principles like statelessness, resource-based routing, HTTP methods, status codes, and idempotency

• Set up a simple Express server to serve as the base for a RESTful API

• Built a complete set of routes (GET, POST, PUT, DELETE) for managing a movies resource

• Used middleware for tasks like JSON parsing and input validation

• Tested routes using Thunder Client and learned how to interact with each HTTP method

• Identified common REST anti-patterns and how to avoid them for cleaner design

To take your API further and follow more advanced RESTful practices, consider:

• Organising routes with Express Router to keep your code modular

• Adding robust error handling to return consistent and informative responses

• Using logging tools like morgan to monitor requests and debug more easily

• Securing endpoints with authentication methods like JWT or API keys

• Structuring responses consistently, possibly with pagination and filtering for larger datasets

• Validating user input thoroughly with libraries like Joi or express-validator

Explore the full project on GitHub, review the code, and try extending it with your features. Happy coding!

That’s where REST APIs come in. They help apps talk to each other – kind of like a waiter taking your order and bringing your food back. And if you're using Django, you're already halfway there.

Django is one of the most popular web frameworks out there. It’s fast, secure, and packed with useful tools. Combine it with Django REST Framework (DRF), and you’ve got everything you need to build a solid REST API without spending weeks figuring it all out.

In this guide, I’ll walk you through the whole process of building a REST API in Django from scratch.

What we’ll cover:

1. What is a REST API?

2. Tools You’ll Need

3. How to Build a REST API in Django

   • Step 1: Set Up Your Django Project

   • Step 2: Create a Model

   • Step 3: Make a Serializer

   • Step 4: Create the Views

   • Step 5: Set Up URLs

   • Step 6: Test It!

4. DRF Permissions

   • Common Built-In Permissions

   • Custom Permissions

   • Combining Permissions

5. FAQs

6. Final Thoughts

What is a REST API?

Before we get started, let’s get one thing straight: What’s even is a REST API?

A REST API (short for “Representational State Transfer”) is a way for two systems – like a website and a server – to talk to each other using standard HTTP methods like GET, POST, PUT, and DELETE.

Let’s say you have a to-do app. You want to:

• Get a list of tasks

• Add a new task

• Update a task

• Delete a task

You can do all of that through a REST API. It’s like setting up your own menu of commands that other apps (or your frontend) can use to work with your data.

Tools You’ll Need:

Here’s what you’ll be using in this tutorial:

• Python (preferably 3.8+)

• Django (web framework)

• Django REST Framework (DRF) (to build APIs)

• Postman or curl (for testing)

You can install DRF with:

pip install djangorestframework

How to Build a REST API in Django

Here is how to get started:

Step 1: Set Up Your Django Project

If you haven’t already, start a new Django project:

django-admin startproject myproject
cd myproject
python manage.py startapp api

• django-admin startproject myproject – Creates a new Django project named myproject, which contains configuration files for your whole site.

• cd myproject – Move into your new project directory.

• python manage.py startapp api – Creates a new Django app named api where your models, views, and API logic will live.

Now add 'rest_framework' and 'api' to your INSTALLED_APPS in settings.py:

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

• rest_framework is the Django REST Framework – it gives you tools to easily create APIs.

• 'api' tells Django to look in the api folder for models, views, and so on.

Step 2: Create a Model

Let’s make a simple model – a task list.

In api/models.py:

from django.db import models

class Task(models.Model):
    title = models.CharField(max_length=200)
    completed = models.BooleanField(default=False)

    def __str__(self):
        return self.title

• title: A short piece of text (like “Buy groceries”). CharField is used for strings.

• completed: A Boolean (True or False) to mark if a task is done.

• __str__: This special method returns a string version of the model when printed – useful for debugging and the admin panel.

Then run:

python manage.py makemigrations
python manage.py migrate

• makemigrations: Prepares the changes to the database schema.

• migrate: Applies those changes to the actual database.

Step 3: Make a Serializer

Serializers turn your Django model into JSON (the data format used in APIs) and back.

In api/serializers.py:

from rest_framework import serializers
from .models import Task

class TaskSerializer(serializers.ModelSerializer):
    class Meta:
        model = Task
        fields = '__all__'

• Serializers convert model instances (like a Task) to and from JSON, so they can be sent over the web.

• ModelSerializer is a shortcut that automatically handles most things based on your model.

• fields = '__all__' means include every field in the model (title and completed).

Step 4: Create the Views

Here’s where the logic goes. You can use class-based or function-based views. Let’s go with class-based using DRF’s generics.

In api/views.py:

from rest_framework import generics
from .models import Task
from .serializers import TaskSerializer

class TaskListCreate(generics.ListCreateAPIView):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer

class TaskDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer

These are generic class-based views provided by Django REST Framework to save you time.

1. TaskListCreate:

   • Handles GET requests to list all tasks.

   • Handles POST requests to create new tasks.

2. TaskDetail:

   • Handles GET for one task, PUT/PATCH for updating, and DELETE to remove a task

Step 5: Set Up URLs

First, make a urls.py file in the api folder (if it doesn’t exist).

In api/urls.py:

from django.urls import path
from .views import TaskListCreate, TaskDetail

urlpatterns = [
    path('tasks/', TaskListCreate.as_view(), name='task-list'),
    path('tasks/<int:pk>/', TaskDetail.as_view(), name='task-detail'),
]

• tasks/: The route to access or create tasks.

• tasks/<int:pk>/: The route to get, update, or delete a single task by its primary key (pk).

Then, in your main myproject/urls.py:

Now, hook this into the main urls.py in your project folder:

from django.contrib import admin
from django.urls import path, include

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

Step 6: Test It!

Start the server:

python manage.py runserver

Open Postman or curl and try hitting these endpoints:

• GET /api/tasks/ – get all tasks

• POST /api/tasks/ – create a new task

• GET /api/tasks/1/ – get a specific task

• PUT /api/tasks/1/ – update a task

• DELETE /api/tasks/1/ – delete a task

And that’s it – you’ve got a working REST API.

This setup gives you a fully functional REST API with just a few lines of code, thanks to Django REST Framework. You should now understand:

• How models define your database structure

• How serializers turn models into JSON and vice versa

• How views control API behaviour (get, post, update, delete)

• How URL routing connects your views to web requests

DRF Permissions

Right now, anyone can use your API. But what if you only want certain users to have access?

DRF gives you simple ways to handle this. For example, to make an API only available to logged-in users:

from rest_framework.permissions import IsAuthenticated

class TaskListCreate(generics.ListCreateAPIView):
    ...
    permission_classes = [IsAuthenticated]

There are more permissions you can use, like IsAdminUser custom permissions, for example.

Let’s break this down and go deeper into permissions in Django REST Framework (DRF), including:

What are Permissions in DRF?

Permissions in DRF control who can access your API and what actions they can perform (read, write, delete, etc.).

They’re applied per view (or viewset), and they're checked after authentication, meaning they build on top of checking whether the user is logged in.

Common Built-In Permissions

DRF gives you a few super useful built-in permission classes out of the box:

1. IsAuthenticated

This one ensures that only logged-in users can access the view:

from rest_framework.permissions import IsAuthenticated

class TaskListCreate(generics.ListCreateAPIView):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer
    permission_classes = [IsAuthenticated]

Only users who have been authenticated (for example, via session login or token) will be able to list or create tasks. Anyone else gets a 403 Forbidden response.

2. IsAdminUser

Only allows access if user.is_staff is True.

from rest_framework.permissions import IsAdminUser

class AdminOnlyView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAdminUser]

Only admin users (usually set via Django admin or superuser status) can access this view.

3. AllowAny

Allows all users, even unauthenticated ones. This is the default for open APIS like sign-up pages.

from rest_framework.permissions import AllowAny

class PublicSignupView(generics.CreateAPIView):
    serializer_class = SignupSerializer
    permission_classes = [AllowAny]

4. IsAuthenticatedOrReadOnly

Authenticated users can read and write, unauthenticated users can only read (GET, HEAD, OPTIONS).

from rest_framework.permissions import IsAuthenticatedOrReadOnly

class ArticleView(generics.RetrieveUpdateAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    permission_classes = [IsAuthenticatedOrReadOnly]

Use case: Great for blogs or article APIS where the public can read but only registered users can write/update.

Custom Permissions

Want more control? You can create your permissions by subclassing BasePermission.

Example: Only allow owners of an object to edit it

from rest_framework.permissions import BasePermission

class IsOwner(BasePermission):
    def has_object_permission(self, request, view, obj):
        return obj.owner == request.user

Then use it like this:

class TaskDetailView(generics.RetrieveUpdateDestroyAPIView):
    queryset = Task.objects.all()
    serializer_class = TaskSerializer
    permission_classes = [IsAuthenticated, IsOwner]

• First, a user must be logged in (IsAuthenticated).

• Then, only the owner of that specific Task can view, update, or delete it.

Combining Permissions

You can combine multiple permission classes, and all must return True for access to be granted.

permission_classes = [IsAuthenticated, IsAdminUser]

This means: user must be both authenticated and an admin.

TL;DR

FAQs

Do I need Django REST Framework to build an API in Django?

Technically, no – but DRF makes your life much easier. Without DRF, you'd have to manually handle things like:

• Parsing and validating JSON requests

• Writing views to serialise Python objects to JSON

• Managing HTTP status codes and responses

• Handling authentication and permissions on your own

In short, you’d be reinventing the wheel – but DRF does all of this for you with far less code.

Can I use this API with a React or Vue frontend?

Absolutely. Your Django API will send and receive data in JSON format — which is exactly what modern frontend frameworks like React and Vue are designed to work with. Just make sure you handle CORS (Cross-Origin Resource Sharing) correctly.

How do I make my API faster?

You can:

• Use caching to store frequent responses

• Enable pagination to reduce data load

• Explore async views (Django 3.1+ supports async) for faster I/O
  DRF also offers built-in tools for pagination, throttling, and more performance tweaks out of the box.

Final Thoughts

Building a REST API in Django might sound like a big job, but it’s just a series of small, manageable steps.

Once you’ve done it once, it gets way easier the next time. Plus, using Django REST Framework saves a ton of time—you’re not reinventing the wheel every time.

Further Resources

Want to keep learning? Here are a few solid places to dig deeper:

• Official Django REST Framework Docs

• Django’s Official Docs

• Simple JWT for token authentication

• Test your API with Postman

• Real Python’s Django API Guide

I hope you're doing well. Whether you're a seasoned coder, a curious learner, or just someone browsing through, welcome to my little corner of the internet.

In this tutorial, we’ll dive into how you can deploy a web service on Microsoft Azure app service. It’s a topic I’ve been excited to explore, and I hope you’ll find it insightful and helpful. So grab a coffee, sit back, and let’s get started.

Prerequisites

• Basic understanding of RESTful web services

• Programming knowledge

• Docker basics

• Docker Hub account

• Command Line Interface (CLI) skills

What we’ll cover:

• Key Terminologies

• How to Install Docker and Docker Compose

• How to Create a Simple Get Client Info Web Service

• How to Build the App’s Docker Image

• How to Run the App in the Container

• How to Create an Azure Resource Group on Azure Portal.

• How to Deploy to Azure App Service

• Conclusion

Before we actually get started, I’d like to go over some key terminologies that I'll be using throughout this tutorial. Understanding these terms will make it easier to follow along and get the most out of what we're discussing. Let’s dive in!

Key Terminologies

1. Docker

Docker is an open-source platform that simplifies application development, shipping, and deployment by using containers. With Docker, there are three key things you can do:

• build once and run anywhere

• keep environment consistent, and

• easily scale your application with container orchestration tools like Kubernetes.

2. Docker Hub

Docker Hub is a cloud-based repository where developers can store, share, and manage Docker images. You can think of it as the GitHub for Docker images 😉.

3. Docker Image

A Docker image is a lightweight, standalone, and executable package that includes everything needed to run a piece of software. You can also think of it as a blueprint for creating and running a container.

Once built, an image is immutable, meaning it cannot change after creation. Instead, you create a new version when updates are needed. This means that you’ll need to rebuild if you update the code that’s being run in the container.

4. Container

A container is a running instance of a Docker image. It provides an isolated environment where an application runs with all its dependencies, without interfering with the host system or other containers.

Wait, what?! 😕 Well, simply put, a container is like a tiny virtual machine that runs the built Docker image. But unlike traditional VMs, it has no init process (PID 1), meaning it always runs on a host system rather than being fully independent. By now, you should be getting the idea: no image, no container. A container depends on an image to exist. You have to cook before you serve, right? 🍽️

5. Azure Resource Group

An Azure resource group refers to a store or folder containing all related resources for an application you want to deploy to production using MS Azure Cloud. For example, if I want to deploy an eCommerce web app with MS Azure, I could create a resource group called EcommWebAppRG. I’d use this to create all the resources I needed for the web app to go live and be accessible – like VMs, DBs, caches, and other services.

Alrighty, now that all the terms are out of the way, lets get started with the tutorial so you can learn how to deploy a web service on Azure App Service.

Since we are deploying an app, let’s start by creating simple REST API app. I’ll be using Golang for the API development, but you can use any programming language/framework of your choice. If you’d like to follow along with the app for this tutorial, I’ve provided the source code here.

How to Install Docker and Docker Compose

To install Docker and Docker compose on your PC, for Mac and Windows you’ll need to download Docker desktop for your Operating System here.

For Linux, you can run the following command:

sudo apt update # update apt registry
sudo apt install docker.io # for docker engine
sudo apt install docker-compose-plugin

After downloading the Docker desktop for your application, open your terminal and enter the following command to verify that Docker and Docker Compose have been successfully installed on your machine:

docker-compose -v # this should show the version of docker compose cli you have on your PC

My Docker Compose version is:

Docker Compose version v2.31.0-desktop.2

docker -v

You should see something similar if Docker has successfully been installed on your machine:

Docker version 27.4.0, build bde2b89

How to Create a Simple Get Client Info Web Service

Alright, I’ll use this handy tool called sparky_generate to generate the app code template. sparky_generate is a command line tool used to generate boilerplate code for backend development using various backend languages and frameworks.

Use this command to install and setup the tool on your Mac or Linux machine. If you are on Windows, you can use WSL.

wget https://raw.githubusercontent.com/Ayobami6/sparky_generate/refs/heads/main/install.sh

chmod 711 install.sh
./install.sh # run the install command like so

sparky # run the sparky command like so

You should see something similar to the below. Select whatever framework you want to use for your backend service.

I will select Go, because I’m using Go for this tutorial. You should have your project template ready once you’ve selected your framework. I won’t go through how to code the web service since it’s out of scope for this tutorial. The goal here is to deploy on Azure using Azure App Service.

How to Build the App’s Docker Image

To build the Docker image for our app, we first need to create a Docker file that will include all the steps needed to build the image.

touch Dockerfile

We will be using a multistage Docker build to reduce the size of our Docker image. We need something as light as possible.

The multistage Docker build helps reduce size because we use different stages for different concerns. This helps ensure that only what’s needed runs the application in the final stage. For example, we might need certain artifacts to build the application, but we don’t need them to run the application. This is why we have the builder and runner stages in the Docker file below.

Our first stage (build) is concerned with building and bundling the application. The second stage (runner) is just used to run the executable we built in the first stage. So basically all files, modules, and so on used in the build process will be discarded in the runner since they’ve already served their purposes.

# using the first stage as build
FROM golang:1.23-alpine AS build # using alpine base image to reduce size

# install git on the machine
RUN apk add --no-cache git

# setting the current work directory on the vm to be /app
WORKDIR /app

# Copying all go dependency files to the working directory
COPY go.mod go.sum ./

# Install go dependencies
RUN go mod download

# copy all remaining files to the working directory
COPY . .
# build the execuatable

# build the go program
RUN go build -o api cmd/main.go

# stage 2 AKA the runner
FROM alpine:3.18

RUN  apk add --no-cache ca-certificates

# copy the go executable to the working directory
COPY --from=build /app/api .

# expose the service running port
EXPOSE 6080

This Dockerfile outlines all the steps for building a Docker image for our app. Lets go through all these steps line by line. Because we are using a multistage build here, our stages are build and runner.

• The first stage build starts from the first FROM golang:1.23-alpine AS build. It initializes a stage with all the steps in the stage. It states that the base image to be used for all the steps in this stage should use a pre-existing golang:1.23 image using an Alpine Linux distro to run all the steps in the stage.

• Next, we have RUN, which is used to run the command apk add git, followed by setting the working directory to the /app folder.

• Then we have the COPY command that copies all the Go dependencies that will run the Go program.

• Following that is RUN go mod download which is used to install all the dependencies.

• We then have the command COPY . . to copy all the files to the working directory /app of the image

• Then the last step in the build stage, RUN go build -o api cmd/main.go, builds the app code main.go to an executable API. The second stage “runner“ uses an alpine:3.18 base image, and also uses the RUN directive to add ca-certificates to the Alpine base image. The COPY is used here to copy just the built executable file from the builder image to the runner image.

• We then expose port 6080 so our built container can accept an HTTP connection from port 6080.

Now, let’s write our docker-compose.yml file to define and run our containerized service::

services:

  client_info_app:
    build: 
      context: .
      dockerfile: Dockerfile
    container_name: info_app

    ports:
      - "6080:6080"

    command: "./api"

Understanding the YAML Structure

YAML follows a key-value structure similar to a dictionary or hashmap. In our file, the top-level key is services, which acts as the parent key. Within services, we define individual service configurations.

In this case, we have a single service named client_info_app, which contains the necessary properties for Docker to build and run it.

• build: This specifies how to build the Docker image for the service. The context: . tells Docker to look for the Dockerfile in the same directory as the docker-compose.yml file.

• container_name: This assigns a custom name (info_app) to the running container, making it easier to reference.

• ports: Defines the port mappings between the host and the container. The - before "6080:6080" indicates that multiple mappings could be listed. Here, port 6080 on the host is mapped to port 6080 inside the container.

• command: Specifies the command to execute inside the container once it starts. In this case, it runs ./api.

This structure allows us to define and configure multiple services within the services key if needed, but for now, we are only defining client_info_app.

How to Run the App in the Container

You can use this command to start the container:

docker-compose up client_info_app

The above command will first build the image if it doesn’t exist. Then it runs it, because remember: no image, no container.

If all looks good, you should have something similar to this, depending on your application framework:

You should also verify that your Docker image has been built as well. To do that, run the following:

docker images

Voilà! You now have your Docker image built and ready for deployment on Azure App Service.

Let’s go on to the Azure Portal to deploy the app.

Note: if you don’t have an active Azure Subscription, that’s fine – you can still follow along. If you want to get a trial account, you can get one here.

How to Create an Azure Resource Group on Azure Portal.

As a reminder, an Azure resource group refers to a store or folder containing all related resources for an application you want to deploy to production using MS Azure Cloud. Now let’s go about creating one.

When you login to the Azure portal, you should see some like this, the dashboard:

Search for Resource group using the search bar:

Click on Create to create a new resource group:

Give your resource group a name and select a region for it. Here I will use the default East US 2, but you can use any you want. Then click on Review + create.

You should see something like the above after creating the resource group.

How to Deploy to Azure App Service

Ok now that we’ve created the resource group, let’s go ahead and create the Azure App Service. To do this, navigate back to the dashboard and click on Create a resource.

You can search for Web App if you don’t see it in the list there. Then click on the Create Web App option:

Here, select the resource group you created earlier, give the app a name, then select Container for the Publish option.

Before you click on Create, go back to your dev workspace (VS Code or whatever IDE you are using) to push your Docker image to Docker Hub so you can add it there before proceeding to the next steps.

But why do you need to push to Docker Hub? Well, first of all, for accessibility – so we can easily share it with others or have other services access it (which is what we need here).

Remember how I compared Docker Hub with Github earlier? Docker Hub helps you host your Docker image on the internet and make it available for others or for various services on the internet to access if you make it public. Otherwise it’s limited to only authorized services.

To push the Docker image to Docker Hub, you first need to tag the Docker image with your Docker Hub username. Go to Docker Docker Hub to register and get your username if you don’t have one.

Run the following:

docker tag client_info_webservice-client_info_app:latest ayobami6/client_info_webservice-client_info_app:latest
# this adds the latest tag to your docker image

This shows that you successfully tagged your image with the latest tag.

Before you actually push the image to Docker Hub, go ahead and login to it with the Docker CLI.

docker login # this will prompt for browser authetication, for the prompt and login your account with your usernam and password

Push the image to Docker Hub like this:

docker push ayobami6/client_info_webservice-client_info_app:latest

You should see something like the below once you enter the push command on Docker Hub.

Alright, now that you have the Docker image on Docker Hub, you can go ahead and deploy it using Microsoft Azure App Service.

Click on the container on the top menu bar to configure the container settings.

Here, select Other container registries.

Select public, because your pushed image is public (meaning it’s publicly accessible over the internet).

Add your Docker image and tag. You can get this when you run the command docker images.

λ MACs-MacBook-Pro ~ → docker images
REPOSITORY                                        TAG         IMAGE ID       CREATED         SIZE
ayobami6/client_info_webservice-client_info_app   latest      a14f2a5b3bd4   2 weeks ago     30.8MB
postgres                                          13-alpine   236985828131   4 weeks ago     383MB
glint_pm_frontend-nextjs                          latest      424233ceaa4b   4 weeks ago     1.72GB
flask_app-flask_app                               latest      ff6ecfc4ba5a   5 weeks ago     203MB
nginx                                             latest      124b44bfc9cc   7 weeks ago     279MB
encoredotdev/postgres                             15          58b55b0e1fc7   10 months ago   878MB
λ MACs-MacBook-Pro ~ →

Copy the repository name and tag – in my case I have ayobami6/client_info_webservice-client_info_app and tag latest → ayobami6/client_info_webservice-client_info_app:latest.

Then add your startup command. If you are not using Go for the development like I am, your startup command will be different – so just use the command you added to your Docker compose command key, like so command: "./api". Copy just the value (mine is ./api) don’t add the double quotes, and add it to the startup command.

This start up command is the command that will start the application from the container and get the container running.

Click on review and create to create the service.

Once the deployment is complete you’ll be redirected here:

Congratulations! You’ve successfully deployed your web service to Azure App Service. You can visit your app using the default domain from the overview. Mine is here.

Conclusion

Deploying a RESTful web service on Microsoft Azure App Service is a powerful way to leverage cloud technology for scalable and efficient application hosting.

Understanding key terms like Docker, Docker Hub, and Azure Resource Groups will help you streamline the deployment process.

This guide walked you through creating a simple web service, building a Docker image, and deploying it on Azure. By following these steps, you can confidently deploy your applications, ensuring they are accessible and performant.

Thank you for following along, and I hope this tutorial has been insightful and helpful in your cloud deployment journey. If you found it useful, feel free to share it with others who might benefit from it. Happy coding and deploying!

Stay tuned for more insightful content, and let's continue learning and growing together. Cheers to building smarter, more efficient solutions with Azure.

This makes it easier to understand, implement, and consume those APIs. And standards matter, as they allow different teams, regardless of their technology stack, to effectively communicate about and work with the same API.

In this practical guide, I’ll want to walk you through all the important parts involved in architecting, implementing, and consuming an API using the OpenAPI standard.

Before we dive in, it's helpful to have a basic understanding of the following:

• The Go programming language

• RESTful APIs

• JSON/YAML

• Basic command-line usage

Table of Contents

1. What is the OpenAPI Specification (OAS)?

2. Architecting the API

   • openapi.yaml

   • Paths and Operations

   • Schemas

   • Extensions

3. How to Generate a Go Server

4. How to visualize API docs

5. Client Code

6. Conclusion

What is the OpenAPI Specification (OAS)?

The OpenAPI Specification (OAS) provides a consistent means to carry information through each stage of the API lifecycle. It is a specification language for HTTP APIs that defines structure and syntax in a way that is not wedded to the programming language the API is created in.

The OpenAPI Specification (OAS) was originally based on the Swagger 2.0 Specification from SmartBear Software. Later it was moved to the OpenAPI Initiative (OAI), a consortium of industry experts under the Linux Foundation.

The main idea of OpenAPI is to be able to describe APIs in agnostic terms, decoupling them from any specific programming language. Consumers of your API specification do not need to understand the guts of your application or try to learn Lisp or Haskell if that’s what you chose to write it in. They can understand exactly what they need from your API specification, written in a simple and expressive language.

This simple and expressive language is called DSL (domain specific language). It can be written in either JSON or YAML.

The latest version of OAS is v3.1.1 and the specification itself is huge. There are many features and corner cases, but we will try to go through the most important ones.

Architecting the API

It all starts with defining what the API should provide for its consumers and what it is for. While this stage isn't always purely technical, having a sketch of your API design in OAS when gathering requirements gives you a head start when starting the design.

Once the requirements are ready, it's time to open your OpenAPI editor and collaborate with your teammates.

And it's important to understand that it's not only about writing the JSON/YAML spec, but actually agreeing on the API design.

I recommend that you follow some API design guide – Google has one, for example. This will help you avoid mixed styles (like /resourceName/{id} and /resource_name/{id}, inconsistent use of HTTP methods, or unclear resource relationships.

openapi.yaml

The spec of your API starts in the entrypoint document openapi.yaml (recommended but not required name) or openapi.json. I've seen very big openapi.yaml files (50k lines), but it's possible to split your spec into multiple parts. Just keep in mind that this may not work well for some OpenAPI tools as they expect a single file. Google Maps OAS is a good example on how to split the schema, but also comes with a pre-processor to generate a single file.

There are some open source tools to bundle the OAS: swagger-cli (archived) and redocly-cli are great options.

swagger-cli bundle -o _bundle/openapi.yaml openapi.yaml

As I mentioned earlier, the spec is huge, but let's break it into smaller parts. For this tutorial I created a dummy "Smart Home" API. You can see the full spec and code here.

The root object is called OpenAPI Object and has the following structure:

# schema version
openapi: 3.1.1

# docs
info:
  title: Smart Home API
  description: API Specification for Smart Home API
  version: 0.0.1

# optional servers for public APIs
servers:
  - url: "https://..."

# tags are used to group the endpoints
tags:
  - name: device
    description: Manage devices
  - name: room
    description: Manage rooms

# endpoints go here
paths:
  # ...

# reusable objects such as schemas, error types, request bodies
components:
  # ...

# security mechanisms, should correspond to components.securitySchemes
security:
  - apiKeyAuth: []

We defined the skeleton of our schema, but the majority of OpenAPI schema lays in the paths and components props.

Paths and Operations

Let's now add a few endpoints to our schema. The operations are grouped by paths, so you can have multiple HTTP methods on a single path – for example GET /devices/{deviceId} and DELETE /devices/{deviceId}.

It's a good practice to define all types (request bodies, responses, errors) in the components section and reference them instead of manually defining them in the paths section. This allows for easier re-use of entities. For example, in our API we have a type Device which can be used in many endpoints.

paths:

  # the path has a parameter in it
  /devices/{deviceId}:
    get:
      tags:
        - device
      summary: Get Device
      operationId: getDevice

      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ULID"

      responses:

        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"

        "404":
          description: Not Found
          content:
            application/json:
              schema:
                # use common type for 404 errors
                $ref: "#/components/schemas/ErrorNotFound"

In the spec above, we defined two endpoints of our API and referenced the types which we still need to define: Device, ErrorNotFound and ULID. Notice that for the deviceId path param we also used a custom type instead of a standard string, which can be helpful in the future in case we want to change the format of our IDs (for example UUID, ULID. integer, and so on).

Notice that each operation has a unique operationId. While it's optional, it's very helpful to set one, so then it can be used on the server and client sides.

This is a basic configuration which you can extend further if you want to. For example, when serving this schema in Swagger, it's good to see the examples of our requests (and their variations). We can define it here in responses section, or directly in our components.schemas.

responses:
  "200":
    content:
      application/json:
        examples:
          new_device:
            value: # any value

Schemas

components is an integral part of OAS, and contains the following properties:

• schemas

• responses

• parameters

• requestBodies

• headers

• securitySchemes

You can see all here.

We could define our Device type like this:

components:
  schemas:
    Device:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ULID'
        name:
          type: string
      required:
        - id
        - name

But later you may have other types that have name or id fields, so it's recommended to define them separately and combine them in the final type using allOf:

components:
  schemas:
    WithId:
      type: object
      required:
        - id
      properties:
        id:
          $ref: "#/components/schemas/ULID"

    WithName:
      type: object
      required:
        - name
      properties:
        name:
          type: string

    Device:
      allOf:
        - $ref: "#/components/schemas/WithId"
        - $ref: "#/components/schemas/WithName"

allOf, oneOf, and anyOf are very powerful techniques for modeling your OAS.

Extensions

OpenAPI schemas can be extended with internal properties that do not affect the schema itself, but are useful for server or client generators. A good example is our ULID type for ids:

ULID:
  type: string
  minLength: 26
  maxLength: 26

  # example is useful for Swagger docs
  example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

  x-go-type: ulid.ULID
  x-go-type-import:
    path: github.com/oklog/ulid/v2

The x- props will be used by the Go server generator to use existing Go types for this field instead of generating a new one.

How to Generate a Go Server

We didn't go through all possible schema properties here and just covered the main ones – so if you’re not familiar with OAS, you should now have a good understanding of this standard. You can read the whole specification here. But now as our schema is ready, we can generate a Go server from it.

You can find the full list of generators on opeanapi.tools – there are a lot of them. But the most popular one for Go servers is oapi-codegen.

oapi-codegen currently doesn’t support this OAS 3.1. issue. ogen does, though.

You can install it via go install:

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

The configuration for the oapi-codegen generator is straightforward. You can either provide command line arguments or specify the same arguments in a yaml configuration file. You can choose which HTTP router to use for the server, where to put the output file, and more. In our case let's use the echo router.

# oapi-codegen.yaml

package: api
output: pkg/api/api.gen.go

generate:
  strict-server: true
  models: true
  echo-server: true

We can now generate the server code using the following command:

oapi-codegen --config=oapi-codegen.yaml openapi.yaml

Let's now explore the generated api.gen.go file.

Since we enabled strict-server, which will generate code that parses request bodies and encodes responses automatically, the interface that we need to implement is called StrictServerInterface:

type StrictServerInterface interface {

  // List Devices
  // (GET /devices)
  ListDevices(ctx context.Context, request ListDevicesRequestObject) (ListDevicesResponseObject, error)

  // Get Device
  // (GET /devices/{deviceId})
  GetDevice(ctx context.Context, request GetDeviceRequestObject) (GetDeviceResponseObject, error)

}

All our types are also generated:

type ULID = ulid.ULID

type Device struct {
    Id   ULID   `json:"id"`
    Name string `json:"name"`
}

// ...

As well as code to parse the requests automatically and the Swagger definition.

Implementation

What's left for us to do is to create a server using echo, implement the generated interface, and glue everything together. We can write the following code in pkg/api/impl.go:

package api

import "context"

type Server struct{}

func NewServer() Server {
    return Server{}
}

func (Server) ListDevices(ctx context.Context, request ListDevicesRequestObject) (ListDevicesResponseObject, error) {
    // actual implementation
    return ListDevices200JSONResponse{}, nil
}

func (Server) GetDevice(ctx context.Context, request GetDeviceRequestObject) (GetDeviceResponseObject, error) {
    // actual implementation
    return GetDevice200JSONResponse{}, nil
}

I skipped the implementation part and just demonstrated how to return the responses. It's quite handy that oapi-codegen generated all possible responses for us.

That leaves us to start the echo server itself. Note that we don't need to write any endpoints manually now, and all request and response parsing is handled for us. Still, we need to validate the requests inside our implementation.

package main

import (
    "oapiexample/pkg/api"

    "github.com/labstack/echo/v4"
)

func main() {
    server := api.NewServer()

    e := echo.New()

    api.RegisterHandlers(e, api.NewStrictHandler(
        server,
        // add middlewares here if needed
        []api.StrictMiddlewareFunc{},
    ))

    e.Start("127.0.0.1:8080")
}

Now when we run our server using go run ., we can curl localhost:8080/devices to see the response!

Supported servers

oapi-codegen supports many web frameworks/servers, such as Chi, Fiber, Gin as well as standard net/http.

How to visualize API docs

Sometimes it's handy to have Swagger docs shipped together with your API – for testing, for example, or just as public documentation. oapi-codegen doesn't generate the Swagger UI out of the box, but we can have a simple HTML page that has a Swagger JS which loads our OAS.

You can find the HTML code for our pkg/api/index.html here.

And then we can use go:embed to embed the static files and add our Swagger endpoint:

//go:embed pkg/api/index.html
//go:embed openapi.yaml
var swaggerUI embed.FS

func main() {
    // ...

    // serve swagger docs
    e.GET("/swagger/*", echo.WrapHandler(http.StripPrefix("/swagger/", http.FileServer(http.FS(swaggerUI)))))
}

Now we can visit localhost:8080/swagger/ to see the Swagger UI with our OAS.

Tools like Postman are very popular for API documentation, and it's also possible to import your existing OpenAPI 3.0 and 3.1 definitions into Postman. Postman supports both YAML and JSON formats.

Generate OAS from code

There is also a practice to generate OpenAPI schemas from code, especially in typed languages. This approach has been popular, with the main selling point being that keeping your OpenAPI schema near the code will hopefully mean that developers keep it up to date as they work on the code.

This is not always the case, which is one of a few reasons this practice is dying out. And I am also not a big fan, as I haven’t seen a big value in this. Anyway, you can have a look at the following projects: go-swagger, swag, swaggest/rest.

Client Code

As mentioned earlier, OpenAPI is very powerful for collaboration between teams, and all you have to do now is to properly version your schema (see info.version part) and distribute it across the teams.

This part can be automated to some extent by packaging your OpenAPI schema and making it available. I've seen devs use Git submodules for that or GitHub actions to publish the version schemas.

Let's assume our client is a web application written in TypeScript, which is quite common for web APIs. Again, there are may generators available at opeanapi.tools online but the most popular one is openapi-typescript.

Here's how you can generate the TypeScript code for local or remote schemas:

# Local schema
npx openapi-typescript openapi.yaml -o ./client/schema.d.ts

# Remote schema
npx openapi-typescript https://.../openapi.yaml -o ./client/schema.d.ts

Conclusion

OpenAPI is a de-facto standard for designing, implementing, and consuming REST APIs, so it's crucial to understand how it works.

I hope this article has provided a useful introduction to the OpenAPI Specification, as well as practical tips and examples for how to use OAS to architect, implement, and consume APIs.

Resources

• Source code

• OpenAPI Initiative

• openapi.tools

• Swagger Editor

• oapi-codegen

• Explore more articles on packagemain.tech

Instead, you can create a REST API directly in the browser without the need of any server. With this, you can showcase your skills in applications that interact with a backend hosted in places where you can't access the server side.

Note that if you search for "API without a server" you may find articles about serverless (which is still a kind of server). This article is completely different and showcases a relatively new browser API. Read on if you're interested.

Table of contents

• What is a Service Worker?

• How to register a Service Worker?

• How to create a basic HTTP response

• How to create a base project

  • Set up Vite

  • Use the Wayne library

  • Install the Service Worker

  • Test on the Web Server

• How to add React authentication

  • Create a JWT token

  • Add authentication API

  • Add authentication to React

• Next steps

• Fully working demo

What is a Service Worker?

The browser API that allows you to create pure in the browser HTTP responses to HTTP requests is called a Service Worker. This API was mostly created to intercept HTTP requests originated from the browser and serve them from cache.

This allows you to create applications called PWA that work when you don't have internet connection. So you can use them while on the train, where you may have unstable internet. When you're offline, the HTTP requests can be stored and sent to the real server when you get back online.

But this is not all what Service Workers can do. With them, you can create HTTP requests that never existed. It can intercept any HTTP requests, for example when you open an image in new tab or using AJAX (like with fetch API).

How to Register a Service Worker?

Service worker needs to be written in a separate file (often called sw.js, but you can name it whatever you want).

The location of that file is important. It should be located in the root of your app, often in the root of the domain.

To register a service worker, you need to execute this code:

if ('serviceWorker' in navigator) {
  var scope = location.pathname.replace(/\/[^\/]+$/, '/')
  navigator.serviceWorker.register('sw.js', { scope })
    .then(function(reg) {
       reg.addEventListener('updatefound', function() {
         var installingWorker = reg.installing;
         console.log('A new service worker is being installed:',
                     installingWorker);
       });
       // registration worked
       console.log('Registration succeeded. Scope is ' + reg.scope);
    }).catch(function(error) {
      // registration failed
      console.log('Registration failed with ' + error);
    });
}

This will install a service worker that can start to intercept HTTP requests.

NOTE: The service worker works only with HTTPS and localhost.

How to Create a Basic HTTP Response

The API of the Service Worker is very simple – you have an event called fetch
and you can respond to that event with any response:

self.addEventListener('fetch', event => {
    const url = new URL(event.request.url);
    if (url.pathname === '/api/hello/') {
        const headers = {
            'Content-Type': 'text/plain'
        };
        const msg = 'Hello, Service Worker!'
        event.respondWith(textResponse(msg, headers));
   }
});

function textResponse(string, headers) {
    const blob = new Blob([string], {
        type: 'text/plain'
    });
    return new Response(blob, { headers });
}

With this you code, you can open the URL /api/hello/ and it will display the text "Hello, Service Worker!" as a text file.

Also, one important thing: if you want to use the Service Worker immediately after it's installed, you need to add this code:

self.addEventListener('activate', (event) => {
  event.waitUntil(clients.claim());
});

Normally, the Service Worker intercepts requests only after you refresh the page. This code forces to accept requests immediately after installation.

NOTE: With service worker, you can also intercept request that are sent to different domains. If you have your app on GitHub pages, you can intercept the requests to any domain. Because there are no checks of the domain, this code:

await fetch('https://example.com/api/hello').then(res => res.text())

will also return Hello, Service Worker!.

How to Create a Base Project

You will create something more useful by creating a React project with very simple user authentication.

Note that this is not secure in any way, because user information and passwords will be visible in the code. But it can show that you know how to interact with an API in React.

Set Up Vite

First, you need to set up a simple React application with Vite.

To use Vite, you need to have Node.js installed. If you don't have it, you can read how to install it from this article.

Then, you need to run this command from the terminal:

npm create vite@latest

I've picked name auth, React, and JavaScript. This is the output I've got:

✔ Project name: … auth
✔ Select a framework: › React
✔ Select a variant: › JavaScript

Scaffolding project in /home/kuba/auth...

Done. Now run:

  cd auth
  npm install
  npm run dev

Next is to modify vite.config.js file, so Vite will know how to build the service worker file/

This is the config file Vite created:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
})

You need to modify the config file to include this code:

import { join } from "node:path";
import { buildSync } from "esbuild";

export default defineConfig({
  plugins: [
    react(),
    {
      apply: "build",
      enforce: "post",
      transformIndexHtml() {
        buildSync({
          minify: true,
          bundle: true,
          entryPoints: [join(process.cwd(), "src", "sw.js")],
          outfile: join(process.cwd(), "dist", "sw.js"),
        });
      },
    },
  ]
})

You need to include both imports and you can replace the existing config with the one above. You can also add the code in the curly braces into a plugin array.

Use the Wayne library

Then, you need to create a Service Worker file named sw.js. You will use Wayne library instead of writing the routes yourself. This will simplify the code.

First, you need to install Wayne:

npm install @jcubic/wayne

Then, you can create a file named sw.js (Note: you've put the "src" directory in the vite.config.js file, so you should save the file in that directory).

import { Wayne } from '@jcubic/wayne';

const app = new Wayne();

app.get('/api/hello/', (req, res) => {
   res.text('Hello, Service Worker!');
});

This code will work exactly the same as our previous example.

Install the Service Worker

Now, the last thing you need to do to set up your service worker is to register it. You could use the code that you saw earlier, but now you will use a library for this.

First, you need to install it:

npm install register-service-worker

And update src/main.jsx with this code:

import { register } from "register-service-worker";

register(`./sw.js`);

The last thing is to build the project by executing:

npm run build

NOTE: the dev mode will not work with the service worker – you need to build the project.

The instructions setting up a Service Worker with Vite were based on this article.

Test on the Web Server

To test your project you can use this command:

npx http-server -p 3000 ./dist/

This will create a simple HTTP server where you can test your application.

NOTE: if you open theindex.html file in a browser (like with drag and drop), the service worker will not work. This is because the file:// protocol has a lot of restrictions. That's why you need a web server.

If you test the app in the browser by opening the URL: http://127.0.0.1:3000, it will run the code that registers the service worker, and you will immediately be able to access our fake HTTP endpoint: http://127.0.0.1:3000/api/hello/. It should display the text:

Hello, Service Worker!

NOTE: to simplify testing, you can add "http-server -p 3000 ./dist/" to the package.json file into scripts:

"serve": "http-server -p 3000 ./dist/",

Remember that package.json is a JSON file, so you can't put a trailing comma if this will be the last script.

To make it work, you need to install the package:

npm install http-server

Now you can run the server with npm run serve.

NOTE: if you access the URL: http://127.0.0.1:3000/api/hello (you can read what is 127.0.0.1 in this article), you will get an error from http-server. This is because the route you created in the service worker used a trailing slash. To fix this, you can add a redirect:

app.get('/api/hello', (req, res) => {
   res.redirect(301, req.url + '/');
});

How to Add React Authentication

Now, after you have set up everything, you can add a real authentication endpoint and connect it with your React app.

Create a JWT token

We will use a popular JWT token for authentication. You can read more about them in this article.

First, you need to install a JWT library:

npm install jose

Then, you need to create a new file named jwt.js in the src directory:

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode(
  'cc7e0d44fd473002f1c42167459001140ec6389b7353f8088f4d9a95f2f596f2'
);

const alg = 'HS256';

const jwt = {
    sign: (payload) => {
        return new SignJWT(payload)
            .setProtectedHeader({ alg })
            .setIssuedAt()
            .setIssuer('https://freecodecamp.org')
            .setAudience('https://freecodecamp.org')
            .setExpirationTime('2h')
            .sign(secret)
    },
    verify: async (token) => {
        const { payload } = await jwtVerify(token, secret, {
            issuer: 'https://freecodecamp.org',
            audience: 'https://freecodecamp.org',
        });
        return payload;
    }
};

export default jwt;

This code is an ES Module that uses the jose JWT token library to create a new token, jwt.sign. It verifies that the token is correct with jwt.verify, and it also returns the payload, so you can extract anything you save in the token.

You can read more about the jose library from the documentation – the links to the docs are in the README.

NOTE: Because of the limitation of Service Worker, we can't create a proper real life authentication, where the access token is stored in a cookie (Service Worker don't allow creating cookies) and use refresh tokens to update the access token.

Add authentication API

Now, you can use the previous functions to create an API endpoint:

import jwt from './jwt';

app.post('/api/login', async (req, res) => {
    const { username, password } = await req.json() ?? {};
    if (username === 'demo' && password === 'demo') {
        const token = await jwt.sign({ username });
        res.json({ result: token });
    } else {
        res.json({ error: 'Invalid username or password' });
    }
});

This code will verify that the username and password are correct (both equal to "demo"), ⁣and create a new JWT token. If the username or password are not correct, it will return an error.

Add authentication to React

You created a React App with Vite, so you need to use JSX to add front-end authentication logic.

First, you create a helper function that will send an HTTP request to the /api/login endpoint with Fetch API:

function login(username, password) {
    return fetch('/api/login', {
        method: 'post',
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            username,
            password
        })
    }).then(res => res.json());
}

Next, you need to create a basic form:

<form>
  <div>
    <label for="user">username</label>
    <input id="user" />
  </div>
  <div>
    <label for="password">password</label>
    <input id="password" type="password" />
  </div>
  <button>login</button>
</form>

And a add bit of styling:

form {
  display: inline-flex;
  flex-direction: column;
  gap: 10px;
  align-items: flex-end;
}

label::after {
  content: ":";
}

label {
  width: 100px;
  display: inline-block;
  text-align: right;
  margin-right: 10px;
}

Next, you need an authentication function that you will add to an onSubmit event. ⁣
You will use two state variables for token and error:

function App() {
  const [token, setToken] = useState(null);
  const [error, setError] = useState(null);

  async function auth(event) {
    event.preventDefault();

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
    } else if (res.error) {
      setError(res.error);
    }
  }

To get the username and password from the form you can use refs. You can also display the form only when the token is not set:

function App() {
  const [token, setToken] = useState(null);
  const [error, setError] = useState(null);
  const userRef = useRef();
  const passwordRef = useRef();

  async function auth(event) {
    event.preventDefault();
    const username = userRef.current.value;
    const username = passwordRef.current.value;

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
    } else if (res.error) {
      setError(res.error);
    }
  }

  return (
    <div>
      <div className="card">
        {!token && (
          <form onSubmit={auth}>
            <div>
              <label for="user">username</label>
              <input id="user" ref={userRef}/>
            </div>
            <div>
              <label for="password">password</label>
              <input id="password" ref={passwordRef} type="password"/>
            </div>
            <button>login</button>
          </form>
        )}
        {error && <p className="error">{ error }</p>}
      </div>
    </div>
  );
}

Now you can test the App. If you type the username and password, they don't reset.

You can fix it by setting the ref value to an empty string at the end of the function:

userRef.current.value = '';
passwordRef.current.value = '';

There is another error. If you put a wrong username or password, you will get an error. But then, if you type the correct password, the error is not removed. To fix this issue, you need to reset the error state when setting the token:

  async function auth(event) {
    event.preventDefault();
    const username = userRef.current.value;
    const username = passwordRef.current.value;

    const res = await login(username, password);
    if (res.result) {
      setToken(res.result);
      setError(null);
    } else if (res.error) {
      setError(res.error);
    }
    userRef.current.value = '';
    passwordRef.current.value = '';
  }

Next thing that you can do is to extract the username from the token. This will also verify that the token is correct in your React app. You need to use the useEffect hook to run the code when the token changes:

import jwt from './jwt';

  // ...
  const [username, setUsername] = useState(null);

  useEffect(() => {
    jwt.verify(token).then(payload => {
      const { username } = payload;
      setUsername(username);
    }).catch(e => {
      setError(e.message);
    });
  }, [token]);

  // ...

If you run this code, you will get an error: Compact JWS must be a string or Uint8Array.

The reason is that the useEffect hook will be triggered when the token is null. Before you verify, you need to check if the token was set:

  useEffect(() => {
    if (token !== null) {
      jwt.verify(token).then(payload => {
        const { username } = payload;
        setUsername(username);
      }).catch(e => {
        setError(e.message);
      });
    }
  }, [token]);

Next, you can display the username after user login:

{token && (
  <div>
    <p>Welcome {username}</p>
  </div>
)}

Next Steps

The last thing we can do is to save the token in localStorage and add a logout button. But this is left as an exercise to the reader.

You can read about localStorage from this freeCodeCamp article.

You can improve this and add more endpoints, like getting real data that you will save in a sw.js file. You can store the data in IndexedDB, so it will be persistent like in in a real app. Read more about IndexedDB from this article.

IndexedDB doesn't have a very nice API, but there are libraries that add abstraction on top of it. My favorite is the SQL library AlaSQL, and idb by Jake Archibald.

Fully working demo

The full source code is available on GitHub in the repository jcubic/react-wayne-auth. You can test a working demo on GitHub pages.

If you like this article, you may want to follow me on Social Media: (Twitter/X and/or LinkedIn) and you an also check my personal website.

In this journey, we'll be creating a delightful recipe management system. We'll explore the power of NestJS, Docker, Swagger, and Prisma, and harness these cutting-edge technologies to implement CRUD (Create, Read, Update, Delete) operations for managing recipes.

But this tutorial isn't just for the culinary enthusiasts or recipe collectors out there. It's for anyone who's passionate about learning and growing their development skills.

So, buckle up and get ready for an exciting coding adventure as we dive in and start building your very own recipe management system together.

This is what we'll build:

A snapshot of the Swagger UI showcasing all the implemented endpoints.

And here's what we'll cover:

Table of Contents

• Technologies
• Prerequisites
• Development Environment
• How to Set Up the NestJS Project
• How to Create a PostgreSQL Instance with Docker
• How to Set Up Prisma
• How to Initialize Prisma
• How to Set Your Environment Variable
• Understanding the Prisma Schema
• How to Model the Data
• How to Migrate the Database
• How to Seed the Database
• How to Create a Prisma Service
• How to Set Up Swagger
• How to Implement CRUD Operations for the Recipe Model
• How to Generate REST Resources with NestJS CLI
• How to Add PrismaClient to the Recipe Module
• How to Define the GET /recipes Endpoint
• How to Define the GET /recipes/:id Endpoint
• How to Define the POST /recipes Endpoint
• How to Define the PATCH /recipes/:id Endpoint
• How to Define the DELETE /recipes/:id Endpoint
• Summary and Final Remarks

Technologies

To build this application, we'll be leveraging the power of the following tools:

• NestJS: A progressive Node.js framework for building efficient, reliable, and scalable server-side applications.
• Prisma: An open-source database toolkit that makes it easy to reason about your data and how you interact with it.
• PostgreSQL: A powerful, open source object-relational database system.
• Docker: An open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly.
• Swagger: A tool for designing, building, and documenting RESTful APIs.
• TypeScript: A statically typed superset of JavaScript that adds optional types, classes, and modules to the language.

Each of these technologies plays a crucial role in creating a robust, scalable, and maintainable application. We'll dive deeper into each one as we proceed.

Prerequisites

Assumed Knowledge

This tutorial is designed to be beginner-friendly, but I do make a few assumptions about what you already know:

• Fundamentals of TypeScript
• Basics of NestJS
• Docker

If you're not familiar with these, don't fret! I've got you covered. This tutorial will guide you through everything you need to know.

But here are some more resources if you'd like to learn more:

• For a deeper dive into NestJS, feel free to explore the official NestJS documentation.
• To learn more about Docker, here's a full handbook for beginners.
• And for more info on TypeScript, here's a helpful crash course.

Development Environment

Tools and Technologies

In this tutorial, we'll use the following tools:

• Node.js – Our runtime environment
• Docker – For containerizing our database
• Visual Studio Code – Our code editor
• PostgreSQL – Our database
• NestJS – Our Node.js framework

Note: Don't forget to install the Prisma extension for Visual Studio Code. It enhances your coding experience by highlighting Prisma-specific syntax and keywords.

How to Set Up the NestJS Project

NestJS is a progressive Node.js framework that comes with a plethora of advantages, including a powerful Command Line Interface (CLI). This CLI simplifies the process of creating a new NestJS application, making it easy to start a new project anytime, anywhere.

One of the key benefits of NestJS is its rich set of built-in functionalities that significantly streamline the development process, making your life as a developer much easier.

Let's begin by installing the NestJS CLI on your system:

npm i -g @nestjs/cli

With the NestJS CLI installed, you're all set to whip up our recipe project. The CLI streamlines the creation of a new NestJS application, making it simple to get started.

To spin up a new project, execute the following command:

nest new recipe

After running this command, you'll encounter a prompt like the one you see below:

The Nest CLI prompting for a package manager selection during project setup.

As illustrated in the image, the Nest CLI will prompt you to select a package manager. For this project, we'll opt for npm. Once you've made your selection, the CLI will proceed with the project setup, and you'll see a series of operations being performed in your terminal.

Now you can open you project in VSCode (or the editor of your choice). You should see the following files:

The folder structure of the project after it has been created using Nest CLI.

Let break down the project structure:

The src directory is the nerve center of our application, hosting the bulk of our codebase. The NestJS CLI has already set the stage for us with several key files:

• src/app.module.ts: This is the root module of our application, serving as the main junction for all other modules.
• src/app.controller.ts: This file houses a basic controller with a single route: /. When accessed, this route will return a simple 'Hello World!' message.
• src/main.ts: This is the gateway to our application. It's tasked with bootstrapping and launching the NestJS application.

To start your project and see the 'Hello World!' message in action, execute the following command:

npm run start:dev

This command triggers a live-reload development server. It vigilantly monitors your files, and if it spots any modifications, it automatically recompile your code and refreshes the server. This ensures that you can see your changes in real-time, eliminating the need for manual restarts.

To verify that your server is operational, head over to http://localhost:3000/ in your web browser or Postman. You should be welcomed by a minimalist page showcasing the message Hello World. This is your application's default landing page, a pristine canvas awaiting your creative touch.

How to Create a PostgreSQL Instance with Docker

To store our recipes REST API, we'll use a PostgreSQL database. Docker will help us containerize this database, ensuring a smooth setup and execution, regardless of the environment.

First, ensure Docker is installed on your system. If not, follow the instructions here.

Next, you'll need to create a docker-compose.yml file.

Open the terminal and run the following command:

touch docker-compose.yml

This command creates a new docker-compose.yml file in your project's root directory.

Open the docker-compose.yml file and add the following code:

# docker-compose.yml

version: '3.8'
services:
  postgres:
    image: postgres:13.5
    restart: always
    environment:
      - POSTGRES_USER=recipe
      - POSTGRES_PASSWORD=RecipePassword
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'
volumes:
  postgres:

Here's a quick breakdown of this configuration:

• image: postgres:13.5: Specifies the Docker image for the PostgreSQL database.
• restart: always: Ensures the container restarts if it stops.
• environment: Sets the username and password for the database.
• volumes: Mounts a volume to persist database data, even if the container is stopped or removed.
• ports: Exposes port 5432 on both the host machine and the container for database access.

Note: If you wish to use a different port, simply change the host machine port. For example, to use port 5433, modify the ports section as follows:

ports:
  - '5444:5432'

Note: Before proceeding, ensure port 5432 is free on your machine. To fire up the PostgreSQL container, execute the following command in your project's root directory (and also make sure you have open the docker desktop app and it is running):

docker-compose up

This command spins up the PostgreSQL container and makes it accessible on port 5432 of your machine. If all goes according to plan, you should see output similar to this:

...
 | PostgreSQL init process complete; ready for start up.
postgres-1  |
postgres-1  | 2024-01-12 14:59:33.519 UTC [1] LOG:  starting PostgreSQL 13.5 (Debian 13.5-1.pgdg110+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv6 address "::", port 5432
postgres-1  | 2024-01-12 14:59:33.526 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
postgres-1  | 2024-01-12 14:59:33.533 UTC [62] LOG:  database system was shut down at 2024-01-12 14:59:33 UTC
postgres-1  | 2024-01-12 14:59:33.550 UTC [1] LOG:  database system is ready to accept connections

Remember, if you've changed the port number, the output will reflect your chosen port.

If the port is already in use, you'll encounter an error message like this:

Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

In such a case, free up the port or choose a different one in your docker-compose.yml file.

Note: if you close the terminal window, it will also stop the container. To prevent this, you can run the container in detached mode. This mode allows the container to run indefinitely in the background.

To do this, add a -d option at the end of the command, like so:

docker-compose up -d

To stop the container, use the following command:

docker-compose down

Congratulations 🎉. You now have your own PostgreSQL database to play around with.

How to Set Up Prisma

Now that we have our PostgreSQL database up and running, we're ready to set up Prisma. Prisma is an open-source database toolkit that makes it easy to reason about your data and how you interact with it.

Prisma is a powerful tool that offers a wide range of features, including:

• Database Migrations: Prisma makes it easy to evolve your database schema over time, without losing any data.
• Database Seeding: Prisma allows you to seed your database with test data.
• Database Access: Prisma provides a powerful API for accessing your database.
• Database Schema Management: Prisma allows you to define your database schema using the Prisma Schema Language.
• Database Querying: Prisma provides a powerful API for querying your database.
• Database Relationships: Prisma allows you to define relationships between your database tables.

You can learn more about Prisma here.

How to Initialize Prisma

To get started with Prisma, we'll need to install the Prisma CLI. This CLI allows us to interact with our database, making it easy to perform database migrations, seeding, and more.

To install the Prisma CLI, execute the following command:

npm install prisma -D

This command installs the Prisma CLI as a development dependency in your project. The -D flag tells npm to install the package as a development dependency.

Next, initialize Prisma in your project by executing the following command:

npx prisma init

This will create a new prisma directory with a schema.prisma file. This is the main configuration file that contains your database schema. This command also creates a .env file inside your project.

How to Set Your Environment Variable

The .env file contains the environment variables required to connect to your database. Open this file and replace the contents with the following:

DATABASE_URL="postgres://recipe:RecipePassword@localhost:5444/recipe"

Note: If you changed the port number in your docker-compose.yml file, ensure you update the port number in the DATABASE_URL environment variable with the port number you used.

This environment variable contains the connection string for your database. It's used by Prisma to connect to your database in the docker container.

Understanding the Prisma Schema

The schema.prisma file contains the schema for your database. It's written in the Prisma Schema Language, a declarative language for defining your database schema. The prisma/schema.prisma file is the main configuration file for your Prisma setup. It defines your database connection and the Prisma Client generator.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

This file is written in the Prisma Schema Language, which is a language that Prisma uses to define your database schema. The schema.prisma file has three main components:

• Generator: This section defines the Prisma Client generator. The Prisma Client generator is responsible for generating the Prisma Client, a powerful API for accessing your database.
• Datasource: This section defines the database connection. It specifies the database provider and the connection string. It use DATABASE_URL environment variable to connect to your database.
• Model: This section defines the database schema. It specifies the database tables and their fields.

How to Model the Data

Now that we have set up our Prisma, we're ready to model our data. We'll be building a recipe management system, so we'll need to define a Recipe model. This model will have various fields.

Open the schema.prisma file and add the following code:

 // prisma/schema.prisma
 // ...
model Recipe {
  id           Int      @id @default(autoincrement())
  title        String   @unique
  description  String?
  ingredients  String
  instructions String
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}

Here's a quick breakdown of this model:

• id: This is the primary key of the Recipe model. It's an auto-incrementing integer that uniquely identifies each recipe. It has the @id attribute, which tells Prisma that this field is the primary key. It also has the @default(autoincrement()) attribute, which tells Prisma to auto-increment this field.
• title: This is the title of the recipe. It's a unique string that's used to identify the recipe.
• description: This is the description of the recipe. It's an optional string that describes the recipe.
• ingredients: This is the list of ingredients used in the recipe. It's a string that contains a comma-separated list of ingredients.
• instructions: This is the list of instructions for preparing the recipe. It's a string that contains a comma-separated list of instructions.
• createdAt: This is the date and time the recipe was created. It's set to the current date and time by default. It has the @default(now()) attribute, which tells Prisma to set this field to the current date and time by default.
• updatedAt: This is the date and time the recipe was last updated. It's set to the current date and time by default.

How to Migrate the Database

Now that we've defined our database schema, we're ready to migrate our database. This will create the database tables and fields defined in our schema.prisma file.

To migrate your database, execute the following command:

npx prisma migrate dev --name init

This command will do three things:

Save the migration: Prisma Migrate will take a snapshot of your schema and figure out the SQL commands necessary to carry out the migration. Prisma will save the migration file containing the SQL commands to the newly created prisma/migrations folder.

Execute the migration: Prisma Migrate will execute the SQL commands in the migration file, creating the database tables and fields defined in your schema.prisma file.

Generate Prisma Client: Prisma will generate Prisma Client based on your latest schema. Since you did not have the Client library installed, the CLI will install it for you as well. You should see the @prisma/client package inside dependencies in your package.json file.

Prisma Client is a TypeScript query builder auto-generated from your Prisma schema. It is tailored to your Prisma schema and will be used to send queries to the database.

If all goes according to plan, you should see output similar to this:

The following migration(s) have been created and applied from new schema changes:

migrations/
  └─ 20220528101323_init/
    └─ migration.sql

Your database is now in sync with your schema.
...
✔ Generated Prisma Client (3.14.0 | library) to ./node_modules/@prisma/client in 31ms

Check the generated migration file to get an idea about what Prisma Migrate is doing behind the scenes:

-- prisma/migrations/20220528101323_init/migration.sql

CREATE TABLE "Recipe" (
    "id" SERIAL NOT NULL,
    "title" TEXT NOT NULL,
    "description" TEXT,
    "ingredients" TEXT NOT NULL,
    "instructions" TEXT NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP(3) NOT NULL,

    CONSTRAINT "Recipe_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "Recipe_title_key" ON "Recipe"("title");

This migration file contains the SQL commands necessary to create the Recipe table. It also contains the SQL commands necessary to create the title field, which is a unique field. This ensures that the title field is unique, preventing duplicate recipes from being created.

How to Seed the Database

Now that we've migrated our database, we're ready to seed it with some test data. This will allow us to test our application without having to manually create recipes.

Firstly, create a seed file called prisma/seed.ts. This file will contain the dummy data and queries needed to seed your database.

Open the terminal and run the following command:

touch prisma/seed.ts

This command creates a new prisma/seed.ts file in your project's root directory.

Next, populate this file with the following code:

// prisma/seed.ts
import { PrismaClient } from '@prisma/client';

// initialize Prisma Client
const prisma = new PrismaClient();

async function main() {
  // create two dummy recipes
  const recipe1 = await prisma.recipe.upsert({
    where: { title: 'Spaghetti Bolognese' },
    update: {},
    create: {
      title: 'Spaghetti Bolognese',
      description: 'A classic Italian dish',
      ingredients:
        'Spaghetti, minced beef, 
        tomato sauce, onions, garlic, olive oil, salt, pepper',
      instructions:
        '1. Cook the spaghetti. 2. Fry the minced beef. 3.
        Add the tomato sauce to the beef.
        4. Serve the spaghetti with the sauce.'
    }
  });

  const recipe2 = await prisma.recipe.upsert({
    where: { title: 'Chicken Curry' },
    update: {},
    create: {
      title: 'Chicken Curry',
      description: 'A spicy Indian dish',
      ingredients:
        'Chicken, curry powder, onions, garlic, 
        coconut milk, olive oil, salt, pepper',
      instructions:
        '1. Fry the chicken. 2. Add the curry powder to the
        chicken. 3. Add the coconut milk.
        4. Serve the curry with rice.'
    }
  });

  console.log({ recipe1, recipe2 });
}

// execute the main function
main()
  .catch(e => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    // close Prisma Client at the end
    await prisma.$disconnect();
  });

This file contains the dummy data and queries needed to seed your database. Let's break it down:

• import { PrismaClient } from '@prisma/client';: This imports the Prisma Client, which is used to send queries to the database.
• const prisma = new PrismaClient();: This initializes the Prisma Client, allowing us to send queries to the database.
• async function main() { ... }: This is the main function that contains the dummy data and queries needed to seed your database.
• const recipe1 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• const recipe2 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• console.log({ recipe1, recipe2 });: This logs the newly created recipes to the console.
• main().catch((e) => { ... });: This executes the main function and catches any errors that occur.
• await prisma.$disconnect();: This closes the Prisma Client at the end.

Now before we can seed our database, we need add a script to our package.json file. Open the package.json file and add the following script:

// package.json

// ...
  "scripts": {
    // ...
  },
  "dependencies": {
    // ...
  },
  "devDependencies": {
    // ...
  },
  "jest": {
    // ...
  },
  // pasting the prisma script here
  "prisma": {
    "seed": "ts-node prisma/seed.ts"
  }

The seed command will execute the prisma/seed.ts script that you previously defined. This command should work automatically because ts-node is already installed as a dev dependency in your package.json.

Now that we've defined our seed script, we're ready to seed the database. To seed your database, execute the following command:

npx prisma db seed

This command will seed your database with the dummy data defined in your prisma/seed.ts file. If all goes according to plan, you should see output similar to this:

Running seed command `ts-node prisma/seed.ts` ...
{
  recipe1: {
    id: 1,
    title: 'Spaghetti Bolognese',
    description: 'A classic Italian dish',
    ingredients: 'Spaghetti, minced beef, tomato sauce, onions, garlic, olive oil, salt, pepper',
    instructions: '1. Cook the spaghetti. 2. Fry the minced beef. 3. Add the tomato sauce to the beef. 4. Serve the spaghetti with the sauce.',
    createdAt: 2024-01-12T16:21:09.133Z,
    updatedAt: 2024-01-12T16:21:09.133Z
  },
  recipe2: {
    id: 2,
    title: 'Chicken Curry',
    description: 'A spicy Indian dish',
    ingredients: 'Chicken, curry powder, onions, garlic, coconut milk, olive oil, salt, pepper',
    instructions: '1. Fry the chicken. 2. Add the curry powder to the chicken. 3. Add the coconut milk. 4. Serve the curry with rice.',
    createdAt: 2024-01-12T16:21:09.155Z,
    updatedAt: 2024-01-12T16:21:09.155Z
  }
}

The seed command has been executed.

Congratulations 🎉. You now have a fully functional database with dummy data.

How to Create a Prisma Service

Now that we've set up Prisma, we're ready to create a Prisma service. This service will act as a wrapper around the Prisma Client, making it easy to send queries to the database.

The Nest CLI gives you an easy way to generate modules and services directly from the CLI. Run the following command in your terminal:

npx nest generate module prisma
npx nest generate service prisma

Note that the generate command can be shortened to g. So, you can also run the following command:

npx nest g module prisma
npx nest g service prisma

This command generates a new module called prisma and a new service called prisma. It also imports the PrismaModule into the AppModule.

So you should see something like this:

  src/prisma/prisma.service.spec.ts
  src/prisma/prisma.service.ts
  src/prisma/prisma.module.ts

Note: In some cases, you may need to restart your server for the changes to take effect.

Next, open the prisma.service.ts file and replace the contents with the following:

// src/prisma/prisma.service.ts

import { Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {}

This service is a wrapper around the Prisma Client, making it easy to send queries to the database. It's also a NestJS provider, which means it can be injected into other modules.

Next, open the prisma.module.ts file and replace the contents with the following:

// src/prisma/prisma.module.ts
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  providers: [PrismaService],
  exports: [PrismaService]
})
export class PrismaModule {}

Note: The PrismaModule is a NestJS module that imports the PrismaService, making it readily available for use across other modules in your application. This setup allows seamless integration of the Prisma service throughout your project.

Congratulations 🎉! You've successfully set up your Prisma service.

Before we dive into writing our application logic, let's set up Swagger. Swagger is an industry-standard tool for designing, building, and documenting RESTful APIs. It empowers developers to create elegant and comprehensive API documentation effortlessly.

How to Set Up Swagger

To configure Swagger, we'll leverage the @nestjs/swagger package. This package offers a suite of decorators and methods specifically designed to generate Swagger documentation.

To install this package, run the following command:

npm install --save @nestjs/swagger swagger-ui-express

This command adds the @nestjs/swagger package as a dependency in your project. It also installs the swagger-ui-express package, which serves the Swagger UI.

Next, navigate to the main.ts file and append the following code:

// src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// Define the bootstrap function
async function bootstrap() {
  // Create a NestJS application instance by passing the AppModule to the NestFactory
  const app = await NestFactory.create(AppModule);

  // Use DocumentBuilder to create a new Swagger document configuration
  const config = new DocumentBuilder()
    .setTitle('Recipes API') // Set the title of the API
    .setDescription('Recipes API description') // Set the description of the API
    .setVersion('0.1') // Set the version of the API
    .build(); // Build the document

  // Create a Swagger document using the application instance and the document configuration
  const document = SwaggerModule.createDocument(app, config);

  // Setup Swagger module with the application instance and the Swagger document
  SwaggerModule.setup('api', app, document);

  // Start the application and listen for requests on port 3000
  await app.listen(3000);
}

// Call the bootstrap function to start the application
bootstrap();

This code initializes Swagger and generates the Swagger documentation. Let's break it down:

• const config = new DocumentBuilder() ... .build();: This creates a new Swagger document builder. It sets the title, description, and version of the Swagger document. It also builds the Swagger document.
• const document = SwaggerModule.createDocument(app, config);: This creates a new Swagger document. It uses the Swagger document builder to generate the Swagger document.
• SwaggerModule.setup('api', app, document);: This sets up the Swagger UI. It uses the Swagger document to generate the Swagger UI.

While the application is running, open your browser and navigate to http://localhost:3000/api. You should see the Swagger UI.

The initial view of the Swagger UI after successful setup.

Now that we've set up Swagger, we're ready to start building our REST API.

How to Implement CRUD Operations for the Recipe Model

In this section we'll implement the CRUD operations for the Recipe model. We'll start by generating the REST resources for the Recipe model. Then we'll add the Prisma Client to the Recipe module. Finally, we'll implement the CRUD operations for the Recipe model.

How to Generate REST Resources with NestJS CLI

Before we can implement the CRUD operations for the Recipe model, we need to generate the REST resources for the Recipe model. This will create the boilerplate code for the Recipe module, controller, service, and DTOs.

To generate the REST resources for the Recipe model, execute the following command:

npx nest generate resource recipe

And it will ask you what type of API you want to generate. So now we will select the REST API .

Check out the below image for reference:

Selecting REST API when creating the CRUD operations using the Nest CLI

This command will generate the following files:

CREATE src/recipe/recipe.controller.ts (959 bytes)
CREATE src/recipe/recipe.controller.spec.ts (596 bytes)
CREATE src/recipe/recipe.module.ts (264 bytes)
CREATE src/recipe/recipe.service.ts (661 bytes)
CREATE src/recipe/recipe.service.spec.ts (478 bytes)
CREATE src/recipe/dto/create-recipe.dto.ts (33 bytes)
CREATE src/recipe/dto/update-recipe.dto.ts (176 bytes)
CREATE src/recipe/entities/recipe.entity.ts (24 bytes)
UPDATE src/app.module.ts (385 bytes)

If you open the Swagger API page again, you should see something like this:

The Swagger UI displaying the newly created CRUD operations.

The swagger page now has a new section called Recipe API . This section contains the REST resources for the Recipe model.

Now when you open Swagger you will see something like this:

• POST /recipes: Create a new recipe.
• GET /recipes: Retrieve all recipes.
• GET /recipes/{id}: Retrieve a specific recipe by its ID.
• PATCH /recipes/{id}: Update a specific recipe by its ID.
• DELETE /recipes/{id}: Delete a specific recipe by its ID.

How to Add PrismaClient to the Recipe Module

Now that we've generated the REST resources for the Recipe model, we're ready to add the Prisma Client to the Recipe module. This will allow us to send queries to the database.

Firstly, open the recipe.module.ts file and add the following code:

// src/recipes/recipes.module.ts

import { Module } from '@nestjs/common';
import { RecipeService } from './recipe.service';
import { RecipeController } from './recipe.controller';
import { PrismaModule } from '../prisma/prisma.module';

@Module({
  imports: [PrismaModule],
  controllers: [RecipeController],
  providers: [RecipeService]
})
export class RecipeModule {}

So now we have imported the PrismaModule and added it to the imports array. This will make the PrismaService available to the RecipeService.

Next, open the recipe.service.ts file and add the following code:

// src/recipes/recipes.service.ts
import { Body, Injectable, Post } from '@nestjs/common';
import { CreateRecipeDto } from './dto/create--recipe.dto';
import { UpdateRecipeDto } from './dto/update--recipe.dto';
import { PrismaService } from 'src/prisma/prisma.service';

@Injectable()
export class RecipesService {
  constructor(private readonly prisma: PrismaService) {}

  //  rest of the code
}

So now we have defined the prisma service as a private property of the RecipeService class. This will allow us to access the PrismaService from within the RecipeService class. So now we use the prisma service to perform the CRUD operations.

Sine we have defined the service for the Recipe model, we're ready to implement the CRUD operations for the Recipe model.

How to Define the GET /recipes Endpoint

Let's kickstart our journey into crafting API endpoints by defining the GET /recipes endpoint. This endpoint will serve as a gateway to fetch all the recipes stored in our database.

In your recipes.controller.ts file, you'll find a method named findAll. This method, as the name suggests, is responsible for fetching all the recipes. Here's how we'll define it:

// src/recipes/recipes.controller.ts

// Other code...

@Get()
async findAll() {
  return await this.recipeService.findAll();
}

// Other code...

In the above code:

• The @Get() decorator maps the findAll method to the GET /recipes endpoint.
• The findAll method invokes the findAll method of the recipeService, which retrieves all the recipes from the database.

As we've previously seen, the Controller is the heart of our application's logic. In this context, we're aiming to implement a findAll method that fetches all recipes from our database. To accomplish this, we'll harness the power of Prisma's services within our recipe.service.ts file.

When you open the recipe.service.ts file you will see something like this :

// Other code...
// src/recipes/recipes.service.ts
 findAll() {
    return `This action returns all recipe`;
  }
// Other code...

NOW we will replace the findAll method with the following code:

// src/recipes/recipes.service.ts
// Other code...

async findAll() {
    return this.prisma.recipe.findMany();
}
// Other code...

In the above snippet:

• The findAll method utilizes Prisma's findMany function to retrieve all recipes from the database.
• The await keyword is not necessary here because the async function implicitly wraps the returned value in a Promise.

We've now successfully implemented the service method that our findAll controller will use to fetch all recipes.

Given that we already have seed data in our database, opening Swagger should allow us to retrieve all the recipes. Here's what you can expect to see:

The Swagger UI displaying the result of the 'Fetch All Recipes' operation.

As depicted in the image above, our GET /recipes endpoint is functioning as expected, successfully fetching all recipes from our database.

This marks a significant milestone in our journey of building a robust recipe management system. Let's continue on and add some more features.

How to Define the GET /recipes/{id} Endpoint

Let's now focus on the GET /recipes/{id} endpoint, which retrieves a specific recipe based on its ID. To implement this, we'll need to modify both the controller and the service.

First, navigate to the recipes.controller.ts file. Here, you'll find the findOne method, which is defined as follows:

// src/recipes/recipes.controller.ts

// other code ...
@Get(':id')
async findOne(@Param('id') id: string) {
  return await this.recipeService.findOne(+id);
}
// other code ...

In this code:

• The @Get(':id') decorator maps to the GET /recipes/{id} endpoint.
• The findOne method accepts an id parameter, which is extracted from the route parameters.

Next, let's turn our attention to the recipes.service.ts file. Here, you'll find a placeholder findOne method:

// src/recipes/recipes.service.ts
// other code ...
  findOne(id: number) {
    return `This action returns a #${id} recipe`;
  }

// other code ...

We'll replace this placeholder with a method that fetches a recipe based on its id:

// src/recipes/recipes.service.ts

findOne(id: number) {
  return this.prisma.recipe.findUnique({
    where: { id },
  });
}

In this code:

• The findOne method takes an id as an argument and uses Prisma's findUnique function to retrieve the recipe with the corresponding id.

With the recent modifications, you've unlocked the ability to fetch individual recipes by their ID.

To see this feature in action, navigate to your Swagger page. Here's a snapshot of what you can expect:

The Swagger UI displaying the result of the 'GET BY ID' operation.

Having achieved this milestone, we're ready to venture into creating our own recipes, adding to the existing ones in our database.

How to Define the POST /recipes Endpoint

The NestJS CLI has conveniently generated a create method for us when we created the resource for the Recipe model. Now, we need to implement the logic for this method in the recipe.service.ts file.

First, let's look at the create method in the recipe.controller.ts file:
We will see something like this:

// src/recipes/recipes.controller.ts

// other code ...
@Post()
create(@Body() createRecipeDto: CreateRecipeDto) {
  return this.recipesService.create(createRecipeDto);
}
// other code ...

In this code:

• The @Post() decorator maps the method to the POST /recipes endpoint.
• The create method accepts a createRecipeDto parameter, which is extracted from the request body.

The NestJS CLI has thoughtfully provided us with DTO (Data Transfer Object) files within the recipe folder. One of these, CreateRecipeDto, will be our tool of choice for validating incoming client data.

A Quick DTO Primer: If you're new to the concept of DTOs, they're essentially objects that carry data between processes. In the context of our application, we'll use DTOs to ensure the data we receive aligns with our expectations. If you're keen to delve deeper into DTOs, check out this comprehensive guide.

Now, let's implement the create method in the recipe.service.ts file to interact with our database.

But before we proceed, let's harness the power of the DTO (Data Transfer Object) folder, generated by the Nest CLI, to model our data.

The CreateRecipeDto class, as shown below, is a prime example of a DTO. It's designed to validate incoming client data, ensuring it aligns with our expectations.

// src/recipes/dto/create-recipe.dto.ts
import { IsString, IsOptional } from 'class-validator';

export class CreateRecipeDto {
  @IsString()
  title: string;

  @IsOptional()
  @IsString()
  description?: string;

  @IsString()
  ingredients: string;

  @IsString()
  instructions: string;
}

In this class, we're using the class-validator package to enforce data validation. This package offers a suite of decorators, such as IsString and IsOptional, which we've employed to validate the title, description, ingredients, and instructions fields.

With this setup, we can confidently ensure that these fields will always be strings, with description being optional.

Now, let's implement the create method in the recipe.service.ts file to interact with our database. When you open the recipe.service.ts file you will see something like this:

// src/recipes/recipes.service.ts

// other code ...
  create(createRecipeDto: CreateRecipeDto) {
    return 'This action adds a new recipe';
  }

// other code ...

Replace the create method with the following code:

// src/recipes/recipes.service.ts

// other code ...
create(createRecipeDto: CreateRecipeDto) {
  return this.prisma.recipe.create({
    data: createRecipeDto,
  });
}
// other code ...

In this code:

• The create method uses Prisma's create function to add a new recipe to the database. The data for the new recipe is provided by the createRecipeDto.

With these changes, you can now create new recipes in your swagger page. Here's what you can expect to see:

The Swagger UI displaying the process of creating a new recipe.

As depicted in the image above, we've successfully added a third recipe to our collection. This demonstrates the effectiveness of our POST method in creating new recipes.

How to Define the PATCH /recipes/{id} Endpoint

Having implemented the endpoints to create and retrieve recipes, let's now focus on updating a recipe. We'll implement the PATCH /recipes/{id} endpoint, which updates a specific recipe based on its ID. This requires modifications in both the controller and the service.

In the recipes.controller.ts file, locate the update method. This method is mapped to the PATCH /recipes/{id} endpoint:

// src/recipes/recipes.controller.ts

// other code ...
@Patch(':id')
update(@Param('id') id: string, @Body() updateRecipeDto: UpdateRecipeDto) {
  return this.recipesService.update(+id, updateRecipeDto);
}
// other code ...

In this code:

• The @Patch(':id') decorator maps the method to the PATCH /recipes/{id} endpoint.
• The update method accepts two parameters: id (extracted from the route parameters) and updateRecipeDto (extracted from the request body).

Next, let's implement the update method in the recipe.service.ts file. When you open the recipe.service.ts file, you will see something like this:

// src/recipes/recipes.service.ts

// other code ...
  update(id: number, updateRecipeDto: UpdateRecipeDto) {
    return `This action updates a #${id} recipe`;
  }

// other code ...

Replace the update method with the following code:

// src/recipes/recipes.service.ts

update(id: number, updateRecipeDto: UpdateRecipeDto) {
  return this.prisma.recipe.update({
    where: { id },
    data: updateRecipeDto,
  });
}

In this code:

• The update method uses Prisma's update function to update the recipe in the database. The where clause specifies the recipe to update (based on id), and the data clause specifies the new data for the recipe (provided by updateRecipeDto).

With the recent modifications, we've unlocked the ability to update individual recipes by their ID.

Let's put this new feature to the test by updating the recipe with an ID of 3.

Here's a snapshot of the current state of the recipe:

Displaying the current data of a specific recipe.

As depicted above, this is the existing data for the recipe we're about to update.

After executing the update operation, here's how our recipe transforms:

Displaying the updated data of a specific recipe after modification.

As you can see, our update operation has successfully modified the recipe, demonstrating the effectiveness of our newly implemented feature.

Let's now turn our attention to deleting recipes.

How to Define the DELETE /recipes/{id} Endpoint

Having successfully defined the GET, POST, and PATCH endpoints, our next task is to implement the DELETE /recipes/{id} endpoint. This endpoint will let us remove a specific recipe using its ID. As with the previous endpoints, we'll need to make modifications in both the controller and the service.

In the recipes.controller.ts file, we have a remove method. This method is mapped to the DELETE /recipes/{id} endpoint:

// src/recipes/recipes.controller.ts

@Delete(':id')
async remove(@Param('id', ParseIntPipe) id: number) {
  return await this.recipesService.remove(id);
}

In this updated code:

• The @Delete(':id') decorator maps the method to the DELETE /recipes/{id} endpoint.
• The remove method accepts an id parameter, which is extracted from the route parameters and parsed to a number using ParseIntPipe.

Next, let's implement the remove method in the recipe.service.ts file. Now with the remove method you see this:

// src/recipes/recipes.service.ts
// other code ...
 @Delete(':id')
  remove(@Param('id') id: string) {
    return this.recipeService.remove(+id);
  }

  // other code ...

Replace the remove method with this code:

// src/recipes/recipes.service.ts


// other code 
async remove(id: number) {
  return await this.prisma.recipe.delete({
    where: { id },
  });
}

// other code ..

In this code, the remove method uses Prisma's delete function to remove the recipe with the specified id from the database.

In this code:

• The remove method uses Prisma's delete function to remove the recipe with the corresponding id from the database.

With these changes, you can now delete individual recipes by their ID. Check the Swagger page to see the updated API documentation.

Displaying the process of deleting a specific recipe.

Summary and Final Remarks

In this handbook, we've journeyed through the process of building a REST API using NestJS and Prisma.

We started by setting up a NestJS project, configuring a PostgreSQL database using Docker, and integrating Prisma.

We then dove into the heart of our application, creating a Recipe model and implementing CRUD operations for it. This involved generating RESTful routes, integrating the Prisma Client into our Recipe service, and crafting the logic for each operation.

This guide serves as a solid foundation for your future projects. Feel free to expand upon it, adding more features and functionalities to suit your needs. Thank you for following along, and happy coding!

REST (which stands for Representational State Transfer) APIs operate on a stateless client-server architecture, providing a standardized way to create, read, update, and delete resources.

Integrating RESTful APIs with React enhances the functionality of your web applications by enabling them to fetch and update data dynamically. This integration facilitates a seamless user experience, ensuring that the application remains responsive and up-to-date.

In this article, we will delve into the fundamentals of RESTful APIs and guide you through the process of working with them in React. From setting up a new React project to handling CRUD operations and implementing authentication, you'll gain a comprehensive understanding of integrating APIs into your React applications

Prerequisites

Before diving into this guide, ensure you have some familiarity with the following:

Conceptual Knowledge:

• JavaScript fundamentals (variables, functions, arrays, objects)
• Basic understanding of web development with HTML and CSS
• Knowledge of RESTful APIs and their operations (GET, POST, PUT, DELETE)

Technical Skills:

• Ability to use a command-line interface (terminal)
• Basic understanding of Node.js and npm package manager

Tools:

• Text editor or IDE for code development
• Web browser

Having these prerequisites will allow you to follow the guide and build your understanding of integrating RESTful APIs with React applications. If you're unfamiliar with any of these concepts, there are plenty of resources available online to help you get up to speed.

Table of Contents

1. Understanding RESTful APIs

2. 1.1 What is REST?

3. 1.2 Key Principles of REST
4. 1.3 Anatomy of a RESTful API

5. 1.4 RESTful API Endpoints

6. How to Set Up a React Project

7. 2.1 Creating a React App

8. 2.2 Installing Dependencies

9. 2.3 Project Structure Overview

10. How to Make API Requests in React

11. 3.1 The Fetch API

12. 3.2 Making GET Requests
13. 3.3 Handling Asynchronous Operations with async/await

14. 3.4 Error Handling

15. How to Display API Data in React Components

16. 4.1 State and Props in React

17. 4.2 Updating State with Fetched Data
18. 4.3 Rendering Data Dynamically

19. 4.4 Loading States and Error Handling

20. CRUD Operations with RESTful APIs

21. 5.1 Creating Data (POST Requests)

22. 5.2 Reading Data (GET Requests)
23. 5.3 Updating Data (PUT/PATCH Requests)

24. 5.4 Deleting Data (DELETE Requests)

25. How to Handle Forms and User Input

26. 6.1 Controlled Components

27. 6.2 Form Submission and Handling
28. 6.3 Sending Data to the API

29. 6.4 Validation and Error Messages

30. Authentication and Authorization

31. 7.1 Understanding Authentication vs Authorization

32. 7.2 Implementing Token-based Authentication

33. 7.3 Securing API Requests

34. How to Optimize Performance

35. 8.1 Caching API Responses

36. 8.2 Lazy Loading and Pagination

37. 8.3 Optimizing Re-rendering with React.memo

38. How to Test Your React App with RESTful APIs

39. 9.1 Unit Testing Components

40. 9.2 Mocking API Requests for Testing

41. 9.3 End-to-End Testing with Tools like Cypress

42. Best Practices and Tips

43. 10.1 Code Organization

44. 10.2 Error Handling Strategies
45. 10.3 Securing API Keys

46. 10.4 Monitoring and Analytics

47. Conclusion

1. Understanding RESTful APIs

1.1 What is REST?

REST (Representational State Transfer) is an architectural style that defines a set of constraints to be used when creating web services. It is not a protocol but a set of principles that dictate how web services should behave.

At its core, REST relies on a stateless client-server communication model, which means that each request from a client contains all the information needed to understand and process the request.

1.2 Key Principles of REST

RESTful APIs follow several key principles, including statelessness, uniform interface, and resource-based interactions.

Statelessness ensures that each request from a client to a server is independent, and the server does not store any information about the client's state between requests. The uniform interface principle defines a standardized way to interact with resources, promoting simplicity and consistency.

1.3 Anatomy of a RESTful API

A RESTful API consists of resources, each identified by a unique URI (Uniform Resource Identifier). These resources can be manipulated using standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE. The API responses typically include data in a format like JSON (JavaScript Object Notation) or XML (eXtensible Markup Language).

1.4 RESTful API Endpoints

Endpoints are specific URLs that represent the resources exposed by a RESTful API. For example, a simple blog API might have endpoints like /posts to retrieve all blog posts and /posts/{id} to retrieve a specific post by its unique identifier.

Understanding these endpoints is crucial when working with RESTful APIs in React, as they define the data you can access and manipulate.

2. How to Set Up a React Project

2.1 Creating a React App:

There are multiple ways to set up a React project. For beginners, a popular option is Create React App (CRA). It provides a pre-configured template with everything you need to get started quickly and easily.

But while CRA remains a viable option, it's worth noting that some limitations exist, such as larger bundle sizes and slower hot module replacement (HMR). The React team actually doesn't recommend its use anymore, as they won't be maintaining it as much moving forward.

For a more modern and performant development experience, you can consider tools like Vite. Vite boasts faster HMR speeds, smaller production builds, and built-in support for modern JavaScript features. Although requiring slightly more initial setup, its flexibility and performance benefits might be compelling for experienced developers.

Using Create React App (CRA)

This option is ideal for beginners or those seeking a straightforward setup. Simply install Node.js and run the following command in your terminal.

npx create-react-app my-app

Replace my-app with your desired project name. Follow the instructions to navigate to the project directory and start the development server using npm start. You'll find the source code in the src folder, ready for you to customize and build your React app.

Using Vite

While beyond the scope of this quick guide, using Vite offers several advantages as mentioned previously. If you're interested in exploring this route, refer to the extensive documentation and tutorials available on the Vite website (https://vitejs.dev/).

2.2 Installing Dependencies

To make API requests and handle asynchronous operations in React, you'll need to install the axios library. Axios is a popular JavaScript library for making HTTP requests.

npm install axios

2.3 Project Structure Overview

The default project structure created by create-react-app is well-organized, with important files and folders like src, public, and node_modules. In the src folder, you'll find the main React components and other files related to your application.

3. How to Make API Requests in React

3.1 The Fetch API

The Fetch API is a modern interface for making HTTP requests in the browser. It provides a more powerful and flexible way to handle network requests compared to older techniques like XMLHttpRequest.

// src/components/ApiExample.js

import React, { useState, useEffect } from 'react';

const ApiExample = () => {
  const [data, setData] = useState([]);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch('https://api.example.com/posts');
        const result = await response.json();
        setData(result);
      } catch (error) {
        console.error('Error fetching data:', error);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      <h1>API Data</h1>
      <ul>
        {data.map((item) => (
          <li key={item.id}>{item.title}</li>
        ))}
      </ul>
    </div>
  );
};

export default ApiExample;

In this example, the useEffect hook is used to fetch data when the component mounts. The fetch function is used to make a GET request to the specified API endpoint ('https://api.example.com/posts'), and the response is converted to JSON using response.json().

3.2 Making GET Requests

When working with RESTful APIs, GET requests are the most common. They retrieve data from the server without modifying it. Let's enhance our example to include query parameters and handle different aspects of the GET request.

// src/components/ApiExample.js

// ... (previous imports)

const ApiExample = () => {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState

(true);

  useEffect(() => {
    const fetchData = async () => {
      try {
        // Simulating a delay to show loading state
        setTimeout(async () => {
          const response = await fetch('https://api.example.com/posts?userId=1');
          const result = await response.json();
          setData(result);
          setLoading(false);
        }, 1000);
      } catch (error) {
        console.error('Error fetching data:', error);
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      <h1>API Data</h1>
      {loading ? (
        <p>Loading...</p>
      ) : (
        <ul>
          {data.map((item) => (
            <li key={item.id}>{item.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
};

export default ApiExample;

In this example, a loading state is introduced to provide feedback to users while the data is being fetched. The loading state is set to true initially and changed to false once the data is fetched.

3.3 Handling Asynchronous Operations with async/await

The use of async/await syntax makes asynchronous code more readable and easier to work with. It allows you to write asynchronous code that looks and behaves similar to synchronous code.

// src/components/ApiExample.js

// ... (previous imports)

const ApiExample = () => {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch('https://api.example.com/posts?userId=1');
        const result = await response.json();
        setData(result);
        setLoading(false);
      } catch (error) {
        console.error('Error fetching data:', error);
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      <h1>API Data</h1>
      {loading ? (
        <p>Loading...</p>
      ) : (
        <ul>
          {data.map((item) => (
            <li key={item.id}>{item.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
};

export default ApiExample;

Here, the fetchData function is declared as an asynchronous function using the async keyword. This allows the use of await inside the function, making the asynchronous code more straightforward and maintaining a clean and readable structure.

3.4 Error Handling

It's essential to handle errors gracefully when making API requests. In the previous examples, we introduced a basic error handling mechanism using try/catch blocks. Let's expand on this to provide more detailed error messages.

// src/components/ApiExample.js

// ... (previous imports)

const ApiExample = () => {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch('https://api.example.com/posts?userId=1');

        if (!response.ok) {
          throw new Error(`HTTP error! Status: ${response.status}`);
        }

        const result = await response.json();
        setData(result);
        setLoading(false);
      } catch (error) {
        console.error('Error fetching data:', error);
        setError('An error occurred while fetching the data. Please try again later.');
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      <h1>API Data</h1>
      {loading ? (
        <p>Loading...</p>
      ) : error ? (
        <p>{error}</p>
      ) : (
        <ul>
          {data.map((item) => (
            <li key={item.id}>{item.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
};

export default ApiExample;

In this example, the response.ok property is checked to determine if the HTTP request was successful. If not, an error is thrown with information about the HTTP status. Additionally, a more user-friendly error message is set in the error state, and it's displayed in the component.

4. How to Display API Data in React Components

4.1 State and Props in React

In React, components manage their internal state, allowing them to dynamically update and re-render based on changes. Props, on the other hand, are used to pass data from parent to child components.

Let's understand how to use state and props to display API data.

import React, { useState, useEffect } from 'react';
import axios from 'axios';

const DisplayData = () => {
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await axios.get('https://api.example.com/data');
        setApiData(response.data);
      } catch (error) {
        console.error('Error fetching data:', error);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      <h2>API Data Display</h2>
      {apiData ? (
        // Render your component using the fetched data
        <MyComponent data={apiData} />
      ) : (
        // Render a loading state or placeholder
        <p>Loading...</p>
      )}
    </div>
  );
};

const MyComponent = ({ data }) => {
  return (
    <div>
      <p>{data.message}</p>
      {/* Render other components based on data */}
    </div>
  );
};

export default DisplayData;

4.2 Updating State with Fetched Data

When the data is successfully fetched from the API, we update the component's state using setApiData(response.data). This triggers a re-render, ensuring the UI reflects the latest information.

4.3 Rendering Data Dynamically

Passing data as props allows components to dynamically render content. In the example, the MyComponent receives data as a prop and renders content based on that data.

4.4 Loading States and Error Handling

Displaying a loading state (<p>Loading...</p>) while waiting for API data ensures a better user experience. Additionally, we've included error handling to catch and log any issues that may arise during the API request.

5. CRUD Operations with RESTful APIs

5.1 Creating Data (POST Requests)

Creating data involves making a POST request to the API. Let's implement a simple form for adding new items.

import React, { useState } from 'react';
import axios from 'axios';

const CreateData = () => {
  const [newData, setNewData] = useState('');

  const handleCreate = async () => {
    try {
      await axios.post('https://api.example.com/data', { newData });
      alert('Data created successfully!');
      // Optionally, fetch and update the displayed data
    } catch (error) {
      console.error('Error creating data:', error);
    }
  };

  return (
    <div>
      <h2>Create New Data</h2>
      <input
        type="text"
        value={newData}
        onChange={(e) => setNewData(e.target.value)}
      />
      <button onClick={handleCreate}>Create</button>
    </div>
  );
};

export default CreateData;

In this example, we capture user input with the useState hook and send a POST request to the API when the "Create" button is clicked.

5.2 Reading Data (GET Requests)

Reading data involves making GET requests to retrieve information from the API. We've already covered this in the previous section on displaying API data.

5.3 Updating Data (PUT/PATCH Requests)

Updating data requires sending a PUT or PATCH request to the API with the modified data. Let's create an example for updating existing data.

import React, { useState } from 'react';
import axios from 'axios';

const UpdateData = () => {
  const [updatedData, setUpdatedData] = useState('');

  const handleUpdate = async () => {
    try {
      await axios.put('https://api.example.com/data/1', { updatedData });
      alert('Data updated successfully!');
      // Optionally, fetch and update the displayed data
    } catch (error) {
      console.error('Error updating data:', error);
    }
  };

  return (
    <div>
      <h2>Update Data</h2>
      <input
        type="text"
        value={updatedData}
        onChange={(e) => setUpdatedData(e.target.value)}
      />
      <button onClick={handleUpdate}>Update</button>
    </div>
  );
};

export default UpdateData;

In this example, we capture the updated data and send a PUT request to the API endpoint for the specific item.

5.4 Deleting Data (DELETE Requests)

Deleting data involves making a DELETE request to the API. Here's an example of how to implement a delete functionality.

import React from 'react';
import axios from 'axios';

const DeleteData = () => {
  const handleDelete = async () => {
    try {
      await axios.delete('https://api.example.com/data/1');
      alert('Data deleted successfully!');
      // Optionally, fetch and update the displayed data
    } catch (error) {
      console.error('Error deleting data:', error);
    }
  };

  return (
    <div>
      <h2>Delete Data</h2>
      <button onClick={handleDelete}>Delete</button>
    </div>
  );
};

export default DeleteData;

In this example, clicking the "Delete" button triggers a DELETE request to the API, removing the specified item.

6. How to Handle Forms and User Input

6.1 Controlled Components

React's controlled components allow us to handle form input dynamically. The value of the input is controlled by the component's state.

import React, { useState } from 'react';

const ControlledComponent = () => {
  const [inputValue, setInputValue] = useState('');

  return (
    <div>
      <h2>Controlled Component</h2>
      <input
        type="text"
        value={inputValue}
        onChange={(e) => setInputValue(e.target.value)}
      />
      <p>Input Value: {inputValue}</p>
    </div>
  );
};

export default ControlledComponent;

6.2 Form Submission and Handling

Forms in React can be submitted by handling the onSubmit event. Let's create a simple form submission example.

import React, { useState } from 'react';

const FormSubmission = () => {
  const [formData, setFormData] = useState({
    username: '',
    password: '',
  });

  const handleInputChange = (e) => {
    setFormData({
      ...formData,
      [e.target.name]: e.target.value,
    });
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    // Perform form submission logic, e.g., send data to API
  };

  return (
    <div>
      <h2>Form Submission</h2>
      <form onSubmit={handleSubmit}>
        <label>
          Username:
          <input
            type="text"
            name="username"
            value={formData.username}
            onChange={handleInputChange}
          />
        </label>
        <label>
          Password:
          <input
            type="

password"
            name="password"
            value={formData.password}
            onChange={handleInputChange}
          />
        </label>
        <button type="submit">Submit</button>
      </form>
    </div>
  );
};

export default FormSubmission;

In this example, the handleInputChange function updates the form data in the component's state, and the handleSubmit function prevents the default form submission and allows you to perform custom logic, such as sending data to an API.

6.3 Sending Data to the API

To send data to the API, integrate the form submission logic with your HTTP request code. Use the appropriate HTTP method (for example, POST) to create new data.

6.4 Validation and Error Messages

Implementing form validation is crucial for ensuring data integrity. You can use conditional rendering to display error messages based on validation rules.

import React, { useState } from 'react';

const FormValidation = () => {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();

    if (!username || !password) {
      setError('Username and password are required.');
      return;
    }

    // Perform form submission logic, e.g., send data to API
  };

  return (
    <div>
      <h2>Form Validation</h2>
      {error && <p style={{ color: 'red' }}>{error}</p>}
      <form onSubmit={handleSubmit}>
        <label>
          Username:
          <input
            type="text"
            value={username}
            onChange={(e) => setUsername(e.target.value)}
          />
        </label>
        <label>
          Password:
          <input
            type="password"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
          />
        </label>
        <button type="submit">Submit</button>
      </form>
    </div>
  );
};

export default FormValidation;

In this example, the error state is used to display an error message when form validation fails.

7. Authentication and Authorization

7.1 Understanding Authentication vs Authorization

Authentication verifies the identity of a user, while authorization determines what actions a user is allowed to perform. Token-based authentication is commonly used for securing APIs.

7.2 Implementing Token-based Authentication

To implement token-based authentication, users typically log in to obtain an access token, which is then sent with each API request for authorization.

import React, { useState } from 'react';
import axios from 'axios';

const Authentication = () => {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');
  const [token, setToken] = useState('');

  const handleLogin = async () => {
    try {
      const response = await axios.post('https://api.example.com/login', {
        username,
        password,
      });

      setToken(response.data.token);
      // Save the token securely (e.g., in local storage)
    } catch (error) {
      console.error('Login failed:', error);
    }
  };

  const handleLogout = () => {
    setToken('');
    // Clear the saved token
  };

  return (
    <div>
      <h2>Token-based Authentication</h2>
      {token ? (
        <button onClick={handleLogout}>Logout</button>
      ) : (
        <div>
          <label>
            Username:
            <input
              type="text"
              value={username}
              onChange={(e) => setUsername(e.target.value)}
            />
          </label>
          <label>
            Password:
            <input
              type="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
            />
          </label>
          <button onClick={handleLogin}>Login</button>
        </div>
      )}
    </div>
  );
};

export default Authentication;

In this example, the handleLogin function sends a POST request with the user's credentials, and upon success, the access token is stored in the component's state.

7.3 Securing API Requests

To secure API requests, include the access token in the request headers. Axios provides an Authorization header for this purpose.

const fetchData = async () => {
  try {
    const response = await axios.get('https://api.example.com/data', {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    // Handle the response
  } catch (error) {
    console.error('Error fetching data:', error);
  }
};

Include this header in all requests that require authentication.

8. How to Optimize Performance

8.1 Caching API Responses

Caching API responses can significantly improve performance. Store fetched data in a state variable or a global state management solution like Redux to avoid unnecessary API calls.

const [cachedData, setCachedData] = useState(null);

const fetchData = async () => {
  try {
    if (cachedData) {
      // Use cached data if available
      return;
    }

    const response = await axios.get('https://api.example.com/data');
    setCachedData(response.data);
    // Handle the response
  } catch (error) {
    console.error('Error fetching data:', error);
  }
};

8.2 Lazy Loading and Pagination

You can implement lazy loading and pagination to optimize the rendering of large datasets. Fetch only the data needed for the current view and load additional data as the user scrolls or navigates.

8.3 Optimizing Re-rendering with React.memo

React.memo is a higher-order component that memoizes functional components, preventing unnecessary re-renders if the component's props haven't changed.

import React, { memo } from 'react';

const MemoizedComponent = memo(({ data }) => {
  return (
    <div>
      <p>{data.message}</p>
      {/* Render other components based on data */}
    </div>
  );
});

export default MemoizedComponent;

Wrap components with React.memo to optimize rendering performance.

9. How to Test Your React App with RESTful APIs

Testing is a crucial part of the development process, ensuring that your application works as expected and remains robust even as it evolves.

In this section, we'll explore different aspects of testing in a React application that interacts with RESTful APIs.

9.1 Unit Testing Components

Unit testing is focused on testing individual units of code in isolation. For React components, this involves testing the component's behavior, rendering, and interactions. We'll use the popular testing library @testing-library/react for our examples.

Let's consider a simple React component that fetches and displays data from a RESTful API:

// src/components/UserProfile.js

import React, { useState, useEffect } from 'react';
import axios from 'axios';

const UserProfile = ({ userId }) => {
  const [user, setUser] = useState(null);

  useEffect(() => {
    const fetchUser = async () => {
      try {
        const response = await axios.get(`https://api.example.com/users/${userId}`);
        setUser(response.data);
      } catch (error) {
        console.error('Error fetching user data:', error);
      }
    };

    fetchUser();
  }, [userId]);

  return (
    <div>
      {user ? (
        <div>
          <h2>{user.name}</h2>
          <p>Email: {user.email}</p>
        </div>
      ) : (
        <p>Loading user data...</p>
      )}
    </div>
  );
};

export default UserProfile;

Now, let's create a unit test for this component:

// src/components/UserProfile.test.js

import React from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import UserProfile from './UserProfile';

test('renders user profile data', async () => {
  // Mocking Axios for unit testing
  jest.mock('axios');
  import axios from 'axios';
  axios.get.mockResolvedValue({ data: { name: 'John Doe', email: 'john@example.com' } });

  // Render the component with a mocked userId
  render(<UserProfile userId={1} />);

  // Check if the loading state is displayed initially
  expect(screen.getByText('Loading user data...')).toBeInTheDocument();

  // Wait for the component to render with fetched data
  const nameElement = await screen.findByText('John Doe');
  const emailElement = screen.getByText('Email: john@example.com');

  // Check if the user data is displayed correctly
  expect(nameElement).toBeInTheDocument();
  expect(emailElement).toBeInTheDocument();
});

This unit test uses Jest and @testing-library/react to ensure that the UserProfile component renders the user data correctly. We mock the Axios library to simulate a successful API response. This way, the test focuses on the component's behavior without making actual network requests.

9.2 Mocking API Requests for Testing

Mocking API requests is essential to isolate components and test their logic without relying on actual network communication. In the previous example, we used Jest's jest.mock to mock the Axios library.

Here's another example with a more complex component that makes multiple API requests:

// src/components/PostList.js

import React, { useState, useEffect } from 'react';
import axios from 'axios';

const PostList = () => {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const response = await axios.get('https://api.example.com/posts');
        setPosts(response.data);
      } catch (error) {
        console.error('Error fetching posts:', error);
      }
    };

    fetchPosts();
  }, []);

  return (
    <div>
      <h2>Posts</h2>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
};

export default PostList;

Now, let's create a test for this component, mocking the API requests:

// src/components/PostList.test.js

import React from 'react';
import { render, screen } from '@testing-library/react';
import axios from 'axios';
import PostList from './PostList';

test('renders a list of posts', async () => {
  // Mocking Axios for unit testing
  jest.mock('axios');
  axios.get.mockResolvedValue({ data: [{ id: 1, title: 'Post 1' }, { id: 2, title: 'Post 2' }] });

  // Render the component
  render(<PostList />);

  // Wait for the component to render with fetched data
  const post1Element = await screen.findByText('Post 1');
  const post2Element = screen.getByText('Post 2');

  // Check if the posts are displayed correctly
  expect(post1Element).toBeInTheDocument();
  expect(post2Element).toBeInTheDocument();
});

In this test, we mock the Axios library to simulate a successful API response containing an array of posts. The test verifies that the PostList component renders the expected posts.

9.3 End-to-End Testing with Tools like Cypress

End-to-End (E2E) testing ensures that your entire application works seamlessly, including interactions between different components. Cypress is a powerful E2E testing tool for web applications, providing a simple API for writing tests.

Let's create a simple Cypress test to ensure that our React application interacts correctly with a RESTful API:

// cypress/integration/api_integration_spec.js

describe('API Integration Tests', () => {
  it('successfully fetches user data from the API', () => {
    cy.intercept('GET', 'https://api.example.com/users/1', { fixture: 'user.json' });

    cy.visit('/user-profile/1');

    cy.get('h2').should('contain.text', 'John Doe');
    cy.get('p').should('contain.text', 'Email: john@example.com');
  });

  it('successfully fetches and displays posts from the API', () => {
    cy.intercept('GET', 'https://api.example.com/posts', { fixture: 'posts.json' });

    cy.visit('/post-list');

    cy.get('li').should('have.length', 2);
    cy.get('li').first().should('contain.text', 'Post 1');
    cy.get('li').last().should('contain.text', 'Post 2');
  });
});

In this Cypress test, we use the cy.intercept command to intercept API requests and respond with predefined fixtures (user.json and posts.json). The test then visits different routes of the application and asserts that the expected data is rendered.

To run Cypress tests, ensure you have Cypress installed:

npm install cypress --save-dev

And add a script to your package.json:

"scripts": {
  "cypress:open": "cypress open"
}

Run Cypress using:

npm run cypress:open

These end-to-end tests help ensure that your entire application, including the interactions with RESTful APIs, functions correctly.

10. Best Practices and Tips

After understanding how to work with RESTful APIs in React and testing your application, it's crucial to adopt best practices for maintaining a clean and efficient codebase. Here are some tips to enhance your development workflow:

10.1 Code Organization

Organizing your code in a structured and consistent manner improves readability and maintainability. Consider the following guidelines:

Separation of Concerns: Divide your application into components, services, and utilities to separate logic and responsibilities.

Folder Structure: Adopt a logical folder structure based on features or modules. For example:

src/
|-- components/
|-- services/
|-- utils/
|-- pages/
|-- ...

Naming Conventions: Use meaningful names for files, components, and variables to make your code self-explanatory.

10.2 Error Handling Strategies

Effective error handling ensures that your application gracefully handles unexpected situations. Consider the following strategies:

Global Error Boundary: Implement a global error boundary in your application to catch and handle errors at the top level.

// src/ErrorBoundary.js

import React, { Component } from 'react';

class ErrorBoundary extends Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    logErrorToService(error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return <h1>Something went wrong.</h1>;
    }

    return this.props.children;
  }
}

export default ErrorBoundary;

Wrap your main component with the ErrorBoundary:

// src/index.js

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import ErrorBoundary from './ErrorBoundary';

ReactDOM.render(
  <React.StrictMode>
    <ErrorBoundary>
      <App />
    </ErrorBoundary>
  </React.StrictMode>,
  document.getElementById('root')
);

Displaying Errors: Provide clear and user-friendly error messages to assist users in understanding what went wrong.

Logging Errors: Implement logging mechanisms to record errors on the server or third-party services for analysis.

10.3 Securing API Keys

When working with APIs, especially third-party services, securing API keys is crucial to prevent unauthorized access and potential misuse. Follow these security practices:

Environment Variables: Store sensitive information, such as API keys, in environment variables rather than hardcoding them in your code.

// src/services/api.js

const API_KEY = process.env.REACT_APP_API_KEY;

// Use API_KEY in your requests

Restricted Access: Ensure that your API keys have the minimum required permissions. Avoid granting unnecessary access to your account.

API Key Rotation: Periodically rotate your API keys to enhance security.

10.4 Monitoring and Analytics

Monitoring your application's performance and user interactions helps identify issues and improve the user experience. Consider integrating the following tools:

Google Analytics: Track user interactions, page views, and user demographics for better insights into user behavior.

Sentry or Bugsnag: Implement error monitoring tools to receive real-time notifications about issues in your application.

Performance Monitoring: Use tools like Lighthouse, New Relic, or Datadog to monitor and optimize your application's performance.

Conclusion

Working with RESTful APIs in React opens up a world of possibilities for building dynamic and data-driven web applications. From fetching and displaying data to handling user input and authentication, this guide has covered a broad range of topics to help you become proficient in integrating APIs with your React projects.

Remember that the key to successful API integration lies in understanding the principles of REST, choosing the right tools and libraries, and following best practices for code organization, error handling, and security. Regular testing, both unit tests and end-to-end tests, ensures the reliability and robustness of your application.

As you continue your journey in React development, stay curious, explore new technologies and trends, and always strive to enhance the performance and user experience of your applications. With the knowledge gained from this guide, you are well-equipped to build powerful and efficient React applications that seamlessly interact with RESTful APIs. Happy coding!

Well, let me introduce you to REST APIs, a powerful tool that you are going to add to your arsenal.

In this article, we are going to learn about REST APIs, what they are, and how to use them as a JavaScript developer.

Table of Contents

1. Introduction and Prerequisites

2. Getting Started with REST APIs

3. How to Make Requests with REST APIs

4. Understanding HTTP Methods

5. How to Handle Responses from the REST API

6. Practical Example: How to Build a Web Application with a Public Rest API

7. Conclusion

Who is this article for?

If you're new to the concept of REST APIs, or have heard about them but feel unsure about how they work, this article is tailor-made for you. It's designed for JavaScript developers who are eager to learn the ropes of working with REST APIs.

What do I need to continue with this article?

To get the most out of this article, you need some basic knowledge of JavaScript, a browser, and a code editor. Sounds good?

What will I learn by the end of this article?

By the end of this article, you'll become acquainted with REST APIs. You'll learn how to make your first API request and handle the responses. You'll also build an IP Address Tracker application to put your skills into practice.

Ip Address Tracker Application

Getting Started with REST APIs

Before we dive into the world of REST APIs, let's take a step back and understand what an API is.

What is an API?

API stands for Application Programming Interface. It acts as a communication channel between two applications, such as a web form submitting data to a database.

Diagram showing how an API helps two applications communicate by requesting and sending data.

From the above image, you can see that the API acts as a bridge between the web form and the database. The API handles the request made from the web form and sends a response back to the web form. In simple terms, that is how APIs work.

What is a REST API?

Now that you know what an API is and how they work, what is REST? REST (Representational State Transfer) is a set of rules (well, you can call them guidelines) that define methods and protocols for how data should be sent, received, and stored.

So basically, REST is a type of API that follows a set of rules that make communication between two applications smooth and organized.

We are not going to go into details about the rules of REST APIs. Here, we just want to know how to use them for now.

There are only two operations that happen when it comes to using APIs: making a request and receiving a response. We are going to focus on these two operations as we go forward.

How to Make Requests with Rest APIs

REST APIs are typically exposed as an Endpoint, a URL that directs your request. For example, there's a REST API called jsonplaceholder providing random user data. The endpoint to get user data looks like this: https://jsonplaceholder.typicode.com/users.

To get the user data, you make a request to that endpoint using JavaScript's Fetch API:

const request = fetch('https://jsonplaceholder.typicode.com/users');
console.log(request.json());

Run the code above to see it in action. You might wonder why you're getting a Promise instead of the data. That's because the Fetch API returns a Promise, and you need to instruct your code to wait for the API response before finishing.

But how do you do that? You can use async/await method in JavaScript like this:

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint);
  const response = await request.json();
  console.log(response);
}

GetData(); // call the function

Or you can use the .then() method:

fetch('https://jsonplaceholder.typicode.com/users')
  .then((response) => response.json())
  .then((json) => console.log(json));

Any of the above would do just fine. If you are not familiar with this code, I wrote a beginner's guide to Promises in JavaScript you can check it out.

Hey, now you know how to make a request and GET data from a REST API. But what if you want to add some data to some database using an API? How would you do that?

Well, we still have to use the fetch API, but this time we have to specify the method to be used. We'll take a look at those methods next.

Understanding HTTP Methods

In addition to the minimal syntax we've seen, the Fetch API takes in some options, and one of those options is the HTTP method.

HTTP methods inform the REST API about the type of request you're making. The common types are POST, GET, PUT, and DELETE, collectively known as CRUD operations (Create, Read, Update, Delete).

Let's look at each HTTP method separately.

GET HTTP Method

This HTTP method is used to read data from the server when using the REST API. To add a method to the Fetch API, you specify it after the endpoint, like this:

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, { method: 'GET' });
  const response = await request.json();
  console.log(response);
}

GetData(); // call the function

When using the Fetch API, it's optional to specify the GET HTTP method. If you don't specify any HTTP method, the Fetch API assumes you're making a GET request. That's why the code you used for your first API request still works fine even without the HTTP method.

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint);
  const response = await request.json();
  console.log(response);
}

GetData(); // call the function

POST HTTP Method

Unlike the GET HTTP method, which retrieves data from an API, the POST HTTP method is used to add data when using REST APIs.

async function AddData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, {
    method: 'POST',
    body: JSON.stringify(data),
  });

  const response = await request.json();
  console.log(response);
}

const data = { username: 'John Snow', age: 22 };

AddData(); // call the function

If you want to add data to the Rest API using this method, you have to specify the POST HTTP method. You can also see that we passed the data we are trying to add to the body option.

Aside from HTTP methods, the Fetch API also has the body option that we can pass our data when adding data to our API. This data we are trying to add is usually in JSON format, which is why we have to convert our Object to JSON using the JSON.stringify() method.

const data = { username: 'John Snow', age: 22 };
const json = JSON.stringify(data);
console.log(json);

PUT HTTP Method

This method is used to update data when working with REST APIs. You use this method along with the data you want to update, just like the POST HTTP method.

Let's update the user with the id 11 we created above.

async function UpdateData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users/2';
  const request = await fetch(endpoint, {
    method: 'PUT',
    body: JSON.stringify(data),
  });

  const response = await request.json();
  console.log(response);
}

const data = { age: 42 }; // update the age

UpdateData(); // call the function

DELETE HTTP Method

This method, as the name implies, is used to delete data permanently from a server when using REST APIs. You don't pass any data to the body when using this method. Let's delete the user we created above:

async function UpdateData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users/2';
  const request = await fetch(endpoint, { method: 'DELETE' });

  const response = await request.json();
  console.log(response);
}

UpdateData(); // call the function

Having learned all this, you can now confidently create, read, update, and delete data from the server by using REST APIs.

Now, when making requests to a REST API, the HTTP method and the body options are not the only things you can specify along with your request. You can also pass along headers with your request.

Headers allow you to provide additional information about the request you are making. For example, we can tell the REST API the type of content we are sending beforehand.

async function AddData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, {
    method: 'POST',
    body: JSON.stringify(data),
    headers: { 'Content-Type': 'application/json' },
  });

  const response = await request.json();
  console.log(response);
}

const data = { username: 'John Snow', age: 22 };

AddData(); // call the function

Theheaders: { "Content-Type": "application/json"} header simply tells the REST API beforehand that we are trying to add data that is in JSON format. Of course, this is completely optional.

Up until now, we have only looked at making requests. lets now look at handling requests from a REST API

How to Handle Responses from the Rest API

Any time you make a request to an API, you will always get a response. There are a couple types of responses you can get back from a Rest API call. You either get a 2XX success response or a 4XX/5XX error response. In your JavaScript code, you'll need to handle these responses accordingly.

Don't worry – we're going to break down what the above responses mean.

Understanding Response codes

As stated above, anytime you make a request, you will always get a response. Depending on the status of your response code, you can determine if a response was successful or not.

2XX Success Status Code

Success responses are usually in the range of 200 to 299 HTTP status codes. The most common success code is 200 OK, indicating that the request was successful. When you receive a successful response, you can handle the data returned by the API.

Here's an example of that shows the status code of our response:

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, { method: 'GET' });
  const response = await request.json();

  console.log(response.status);
}

GetData(); // call the function

If you get a 200 status code, it means that the request was successful and OK.

We should always use this status code to check if our request was successful before we try to use the data returned from an API request.

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, { method: 'GET' });
  const response = await request.json();

  if (request.status == 200) {
    // Request was successful
    console.log(request.status);
  }
}

GetData(); // call the function

Additionally, you can also use theResponse.ok property to check if the request was successful; this property will return true if the request was successful.

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint, { method: 'GET' });
  const response = await request.json();

  if (response.ok) {
    // Request was successful
    console.log(response.status);
  }
}

GetData(); // call the function

4XX/5XX Error Status Code

When you make a request to an API, and you don't receive a success status code, you will either get a 400-499 or 500-599 error code. The error code you will receive will fall into one of these ranges.

Both of these status codes usually indicate an error. The 400–499 error codes indicate that there's something wrong with your request, while the 500–599 error codes indicate that error is coming from the server.

Consider the example below where we intentionally made a request to a non-existent endpoint (https://jsonplaceholder.typicode.com/nonexistent) to trigger a 404 Not Found error.

async function AddData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/nonexistent';
  const request = await fetch(endpoint, {
    method: 'POST',
    body: data, // don't convert the data to json
  });

  const response = await request.json();

  if (response.ok) {
    console.log(response);
  } else {
    console.log(`An error with status code ${response.status} occured`);
  }
}

const data = { username: 'John Snow', age: 22 };

AddData(); // call the function

The status code 404 we received here indicates that there's something wrong with our request.

I did not cover all the status codes here, but if you are looking for a comprehensive list of the status codes, you can take a look at this guide.

Now depending on the response you receive, you can show different things to your users.

• if you receive a success status code, you can use the data to build your application as you deem fit

• If you receive an error status code, you can show an Error message to your users as well

How to handle the response body

Depending on the type of request you make, you are going to get back data as a response. To get this data we use the request.json();. We have used this a couple of times already – it will get the request body and parse the data back to an object that we can use.

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint);

  const response = await request.json(); // parse the data

  console.log(response);
}

GetData(); // call the function

You don't need to do anything else in order to process the data returned from your API request.

Aside from the request body, you also get the headers along with the response. This can be useful if, for example, you want to check the type of data returned by your API request beforehand:

async function GetData() {
  let endpoint = 'https://jsonplaceholder.typicode.com/users';
  const request = await fetch(endpoint);

  const dataType = request.headers.get('content-type');

  if (dataType.includes('application/json')) {
    const response = await request.json(); // parse the data
    console.log(response);
  } else {
    console.log('We expected the data to be in json format');
  }
}
GetData(); // call the function

Well, enough of all the talk. Let's roll up our sleeves and try a practical example.

Practical Example: How to Build a Web Application with a Public Rest API

I feel like we have learned a lot already, so let's put our new Rest API skills into practice, shall we?

Our task is to build a web application with an IP address API. It'll retrieve information about an IP address and display the location of the IP address on a map with some other information. This is what it is supposed to look like:

Application we'll build

To build this we are going to use:

• IP Geolocation API by IPify to get the IP address locations.

• The endpoint for the API: https://geo.ipify.org/api/v2/country,city?apiKey=XXXXXXXX&ipAddress=XXXXXXX

• To get the API key you have to sign up for an account with IPify

• To generate the map, we are going to be using LeafletJS

Now that we have that out of the way, let's build the HTML and CSS of the web application. If you are confident about your HTML and CSS skills, try building the web page on your own. Here's my implementation:

Now that we have the HTML and CSS out of the way, the first thing we need to do is to get the IP address the user entered. So create a index.js file and add the following code:

/* Select form */
const search_form = document.querySelector('.header_form');

search_form.addEventListener('submit', (event) => {
  /* stop form from auto submiting on click */
  event.preventDefault();

  /* get the value of the form field */
  const value = document.querySelector('#search').value;

  console.log(value);
});

Submit the the form to see the value that you entered in the HTML input form.

Next we need to pass that value into a function search_Ip_Address(). It actually makes a GET request to fetch our location data and uses the data to update the UI of our web application:

/* Select form */
const search_form = document.querySelector('.header_form');

search_form.addEventListener('submit', (event) => {
  /* stop form from auto submiting on click */
  event.preventDefault();

  /* get the value of the form field */
  const value = document.querySelector('#search').value;

  /* Pass the Ip address to the search_Ip_Address() function */
  search_Ip_Address(value);
});

/* Search for an IpAddress */
async function search_Ip_Address(ip_address) {
  const api_key = 'xxxxxxxxxxxxxxxxxxxxxxx';
  const request = await fetch(
    `https://geo.ipify.org/api/v2/country,city?apiKey=${api_key}&ipAddress=${ip_address}`,
  );
  const response = await request.json();

  /* Update the UI on the page */
  const { location, ip, isp } = response;
  update_ui(ip, location.city, location.timezone, isp);
}

/* update UI function */
function update_ui(ip_address, location, timezone, isp) {
  /* select all the elements on the page */
  const address = document.querySelector('.address');
  const city = document.querySelector('.location');
  const utc = document.querySelector('.utc');
  const isprovider = document.querySelector('.isp');

  /* Update all the elements on the page */
  address.textContent = ip_address;
  city.textContent = location;
  utc.textContent = 'UTC' + timezone;
  isprovider.textContent = isp;
}

Next we need to create our map. To begin, add the following to the head section of your HTML file:

<head>
  ...
  <link
    rel="stylesheet"
    href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
    integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
    crossorigin=""
  />
  <script
    src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
    integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
    crossorigin=""
  ></script>
  ...
</head>

Also make sure you have a div element on the page with an id of map:

<div class="map" id="map"></div>

Next we need to create a function that will create the map for us. So in your script.js add the following code:

/* create the map */
let map;
function create_map(lat, lng) {
  map = L.map('map').setView([lat, lng, country, region], 14);
  L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
    maxZoom: 20,
    attribution:
      '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
  }).addTo(map);

  L.marker([lat, lng])
    .addTo(map)
    .bindPopup(`${region}, ${country}`)
    .openPopup();
}

Lastly we just need to call the create_map() function any time the user searches for an IP address.

To call the create_map() when the user searches for an Ip address, update the search_Ip_Address() function:

/* Search for an IpAddress */
async function search_Ip_Address(ip_address) {
  const api_key = 'at_HhKzCe09UZIYJC9pY7YTg7kMMUzZd';
  const request = await fetch(
    `https://geo.ipify.org/api/v2/country,city?apiKey=${api_key}&ipAddress=${ip_address}`,
  );
  const response = await request.json();

  const { location, ip, isp } = response;

  /* Update the ui on the page */
  update_ui(ip, location.city, location.timezone, isp);

  /* Update the map on the page */
  /* first remove all map instances if any */
  if (map !== undefined && map !== null) {
    map.remove();
  }
  create_map(location.lat, location.lng, location.country, location.region);
}

Lastly, just call the search_Ip_Address() function when the page finishes loading:

const defaultIp = '197.210.78.172';
search_Ip_Address(defaultIp);

And there you go – a nice IP tracker web application. I hope that building this application helped you reinforce your newfound REST API skills.

To provide you with an opportunity for practice, here's a challenge you can undertake. Below is the final preview of the web app:

Challenge:

Currently, our IP tracker application lacks error handling. For instance, if a user enters a random word in the search input field that is not a valid IP address, the entire application will break.

As conscientious developers, we should always be vigilant about errors and handle them gracefully. Therefore, your challenge is twofold:

1. Implement input validation to ensure that the entered value is always a valid IP address. If the user enters an invalid IP address, display an error message.

2. Handle all unforeseen errors that users may encounter during the application's usage.

Conclusion

Knowing how to work with REST APIs is a key skill that developers must have. In this article, you learned about REST APIs and how to use them to develop your own applications.

If you have any questions, feel free to message me on Twitter at @sprucekhalifa, and don't forget to follow me for more insights and updates. Happy coding!

The example used in this tutorial was gotten from frontendmentor.io IP address tracker challenge on Frontend Mentor.