Tutorial part 1: project and first route¶
In this tutorial, you build the API of a small publishing site. Authors write articles. Readers list and read them.
The tutorial has four parts:
- Create the project and a first route. (This page.)
- Add an
Articlemodel and the routes to list, read, create, change and delete articles. - Add JWT authentication. Only the author of an article can change it.
- Write tests, and run the server with several processes.
You must know Python and the basics of Django. If Django is new to you, do the Django tutorial first. You need Python 3.12 or later. For the full list of requirements, see Installation.
Create a virtual environment¶
Make a directory for the project, and create a virtual environment in it:
On Windows, activate the environment with .venv\Scripts\activate.
Install Django-Bolt¶
This also installs Django. Check the version of Django-Bolt:
Create the Django project¶
Create a project with the name mysite in the current directory:
The directory now has this structure:
Add Django-Bolt to the project¶
Add "django_bolt" to the end of INSTALLED_APPS:
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"django_bolt",
]
Create the database tables of Django:
Operations to perform:
Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
...
Applying sessions.0001_initial... OK
Add your first route¶
Create the file mysite/api.py:
from django_bolt import BoltAPI
api = BoltAPI()
@api.get("/hello")
async def hello() -> dict:
return {"message": "Hello from Django-Bolt"}
BoltAPI holds the routes of your API.
@api.get("/hello") connects the route GET /hello to the handler hello.
The handler returns a dict, and Bolt sends it as JSON.
You do not add this file to urls.py.
runbolt finds an api.py file in the project package and in each installed app.
For the rules, see How runbolt finds your APIs.
Start the server¶
System check identified no issues (0 silenced).
⚡ Django Bolt v0.13.0 ready in 446 ms
➜ Local: http://127.0.0.1:8000
➜ Docs: http://127.0.0.1:8000/docs
➜ Admin: http://127.0.0.1:8000/admin/
Mode development · auto-reload
Routes 1 API · 1 ASGI · +8 framework · 1 app
Workers 1 process
Compression enabled
Middleware 9 handlers
press CTRL+C to stop
runbolt is the HTTP server of Django-Bolt. It replaces runserver in development, and gunicorn or uvicorn in production.
--dev restarts the server when you change a Python file. Keep it running for the rest of the tutorial.
The banner shows:
1 API: your routeGET /hello.1 ASGI: the Django admin, at/admin/.+8 framework: the routes that Bolt adds for the API docs at/docs.
Send a request¶
Open a second terminal and send a request:
The terminal of the server logs the request:
Open the API docs¶
Open http://127.0.0.1:8000/docs in a browser.
Bolt makes an OpenAPI schema from your routes, and shows it in Swagger UI.
Click GET /hello, then Try it out, then Execute. The page sends the request and shows the response.
The schema is at http://127.0.0.1:8000/docs/openapi.json.
To change the title or the UI, see OpenAPI.
Summary¶
You made a Django project that serves an API with runbolt.
You did not change urls.py, and you did not install an app server.