Skip to content

Quickstart

Build a working blog API in 5 minutes.

1. Create a project

buraq startproject myblog
cd myblog
uv sync

2. Create an app

python manage.py startapp posts

3. Define a model

posts/models.py
from buraq import models


class Post(models.Model):
    title        = models.CharField(max_length=200)
    slug         = models.SlugField(max_length=200, unique=True)
    content      = models.TextField()
    is_published = models.BooleanField(default=False)
    created_at   = models.DateTimeField(auto_now_add=True)

4. Write views

posts/views.py
from buraq.shortcuts import render, redirect, get_object_or_404
from posts.models import Post


async def post_list(request):
    posts = await Post.objects.filter(is_published=True).order_by("-created_at")
    return render(request, "posts/list.html", {"posts": posts})


async def post_detail(request, slug: str):
    post = await get_object_or_404(Post, slug=slug)
    return render(request, "posts/detail.html", {"post": post})

5. Wire up URLs

posts/urls.py
from buraq.urls import path
from posts import views

urlpatterns = [
    path("/",           views.post_list,   name="post_list"),
    path("/<str:slug>", views.post_detail, name="post_detail"),
]
config/urls.py
from buraq import Buraq
from buraq.urls import path, include

app = Buraq(settings_module="config.settings")

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

app.load_urls(urlpatterns)

6. Add the app to settings

config/settings.py
INSTALLED_APPS = [
    "buraq.contrib.auth",
    "posts",  # add this
]

7. Create the database tables

python manage.py migrate

8. Run the server

python manage.py runserver

Visit http://127.0.0.1:8000/posts/ — your blog is live.

Auto-generated API docs: http://127.0.0.1:8000/api/docs