A List API is the foundation of any RESTful service—it allows clients to retrieve collections of data, such as a list of books, users, or products.

In this tutorial, you’ll learn how to create a basic GET /items/ API endpoint using Django REST Framework.

We’ll cover:

• What a List API is

• Project setup

• Creating models, serializers, and views

• Writing the urls.py

• Testing the List API

• Common issues and tips

What is a List API?

A List API is an endpoint that returns a list of objects (e.g., all books, posts, comments, etc.) in JSON format.

GET /books/

Response:

[
  {"id": 1, "title": "Book A", "author": "Author A"},
  {"id": 2, "title": "Book B", "author": "Author B"}
]

⚙️ Step-by-Step: Creating a Basic List API

Let’s create a simple Books API that returns a list of all books in the database.

1. Setup Django & Django REST Framework

Install and set up Django and DRF:

pip install django djangorestframework
django-admin startproject myapi
cd myapi
python manage.py startapp books

Add rest_framework and books to INSTALLED_APPS in settings.py.

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'books',
]

2. Define a Model

# books/models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=100)

    def __str__(self):
        return self.title

Run migrations:

python manage.py makemigrations
python manage.py migrate

3. Create a Serializer

# books/serializers.py
from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = '__all__'

4. Create a View (ListAPIView)

# books/views.py
from rest_framework.generics import ListAPIView
from .models import Book
from .serializers import BookSerializer

class BookListView(ListAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

✅ ListAPIView is a DRF generic view that handles GET requests and returns a list of objects.

5. Add the URL Pattern

# books/urls.py
from django.urls import path
from .views import BookListView

urlpatterns = [
    path('books/', BookListView.as_view(), name='book-list'),
]

Include this in the main urls.py:

# myapi/urls.py
from django.contrib import admin
from django.urls import path, include

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

✅ Testing the List API

Start the server:

python manage.py runserver

Visit:

http://127.0.0.1:8000/api/books/

If you have books in the database, you’ll see a JSON list like:

[
  {"id": 1, "title": "Clean Code", "author": "Robert Martin"},
  {"id": 2, "title": "Django for APIs", "author": "William S. Vincent"}
]

Common Issues

Tips

• Use the Django admin to add test data quickly

• Add pagination by setting REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS']

• Secure the API with authentication later on (permissions, throttling, etc.)

• Consider adding filters and search functionality using django-filter

Summary

You now have a working List API using Django REST Framework that’s clean, extendable, and production-ready.

Next Steps

Once you're comfortable with the List API, try building:

• Detail API (GET /books/<id>/)

• Create API (POST /books/)

• ViewSets + Routers for cleaner API design

• Authentication using DRF Tokens or JWT