Part 4: A REST API
The blog has an admin for writers. Readers, mobile apps and frontends need an API. In this part
you will build one with @ghuri/rest, which follows Django REST framework closely.
Serializers
Section titled “Serializers”A serializer turns model instances into JSON-ready objects and validates incoming data before
it reaches your models. Open src/blog/serializers.ts:
import { CharField, ModelSerializer, SerializerMethodField, SlugRelatedField, ValidationError,} from '@ghuri/rest'import { Comment, Post, Tag } from './models'
export class TagSerializer extends ModelSerializer<Tag> { static Meta = { model: Tag, fields: ['id', 'name'] }}
export class CommentSerializer extends ModelSerializer<Comment> { static Meta = { model: Comment, fields: ['id', 'post', 'authorName', 'body', 'createdAt'], readOnlyFields: ['post'] } authorName = new CharField({ source: 'author.username', readOnly: true })}
export class PostSerializer extends ModelSerializer<Post> { static Meta = { model: Post, fields: ['id', 'title', 'slug', 'summary', 'body', 'published', 'authorName', 'tags', 'commentCount', 'createdAt'], } authorName = new CharField({ source: 'author.username', readOnly: true }) tags = new SlugRelatedField({ slugField: 'name', many: true, queryset: Tag.objects.all(), required: false }) commentCount = new SerializerMethodField()
async getCommentCount(post: Post) { return post.comments.filter({ approved: true }).count() }
validateTitle(value: string) { if (value.toLowerCase().includes('lorem ipsum')) { throw new ValidationError('Write a real title.') } return value }}ModelSerializer reads the model’s fields and builds matching serializer fields, with the same
validation rules (maxLength, unique, choices). You override or add fields as class
properties: here authorName follows the author relation, tags uses tag names instead of
ids, and commentCount is computed by a method named get<FieldName>.
validate<FieldName> methods validate a single field, and validate(attrs) validates the
object as a whole.
Here is what using it looks like (the shell only preloads models, so try this in a test or a view):
const s = new PostSerializer(await Post.objects.get({ slug: 'hello-ghuri' }))await s.getData()// { id: 1, title: 'Hello, Ghuri', slug: 'hello-ghuri', summary: '', body: '', published: true,// authorName: 'rifat', tags: ['typescript'], commentCount: 1, createdAt: '2026-11-12T08:14:03.201Z' }
const input = new PostSerializer({ data: { title: 'lorem ipsum', slug: 'hello-ghuri' } })await input.isValid() // falseinput.errors// { title: ['Write a real title.'], slug: ['post with this slug already exists.'] }
await input.isValid({ raiseException: true }) // throws ValidationError: a 400 response in a viewA model instance can be passed directly; the full form is
new PostSerializer({ instance, data, partial, context, many }).
Serializing is asynchronous (await s.getData()), because fields such as authorName and
commentCount may need the database. That is the main difference from DRF, where
serializer.data is a plain property.
Viewsets
Section titled “Viewsets”A viewset groups the views for one resource. ModelViewSet provides list, create,
retrieve, update, partialUpdate and destroy. Add these to src/blog/views.ts (the
function views from Part 1 can stay):
import { action, APIResponse, type APIRequest, FieldFilter, IsAdminUser, IsAuthenticatedOrReadOnly, ModelViewSet, OrderingFilter, ReadOnlyModelViewSet, SearchFilter,} from '@ghuri/rest'import { Post, Tag } from './models'import { IsAuthorOrReadOnly } from './permissions'import { CommentSerializer, PostSerializer, TagSerializer } from './serializers'
export class PostViewSet extends ModelViewSet<Post> { serializerClass = PostSerializer permissionClasses = [IsAuthenticatedOrReadOnly, IsAuthorOrReadOnly.or(IsAdminUser)] filterBackends = [SearchFilter, OrderingFilter, FieldFilter] searchFields = ['title', 'body'] orderingFields = ['createdAt', 'title'] filtersetFields = ['published', 'tags__name'] lookupField = 'slug'
getQueryset() { const qs = Post.objects.selectRelated('author').prefetchRelated('tags') // Anonymous readers only see published posts; signed-in users also see drafts. const user = this.request.user return user.isAuthenticated ? qs : qs.filter({ published: true }) }
async performCreate(serializer: PostSerializer) { await serializer.save({ author: this.request.user }) }
@action({ detail: true, methods: ['post'] }) async publish(request: APIRequest) { const post = await this.getObject() post.published = true await post.save({ updateFields: ['published'] }) return new APIResponse({ status: 'published' }) }
@action({ detail: true, methods: ['get', 'post'] }) async comments(request: APIRequest) { const post = await this.getObject() if (request.method === 'POST') { const serializer = new CommentSerializer({ data: request.data }) await serializer.isValid({ raiseException: true }) await serializer.save({ post, author: request.user }) return new APIResponse(await serializer.getData(), 201) } const comments = await post.comments.filter({ approved: true }).selectRelated('author') return new APIResponse(await new CommentSerializer({ instance: comments, many: true }).getData()) }}
export class TagViewSet extends ReadOnlyModelViewSet<Tag> { queryset = Tag.objects.all() serializerClass = TagSerializer}Handlers, including @action methods, receive the REST request (request.data,
request.user, request.query, and the Hono context as request.c); this.request is the same
object. @action is a standard TC39 decorator; without decorators, write
static actions = { publish: action({ detail: true, methods: ['post'] }) }.
A custom permission keeps people from editing each other’s posts. Create
src/blog/permissions.ts:
import { type APIRequest, BasePermission, SAFE_METHODS } from '@ghuri/rest'import type { Post } from './models'
export class IsAuthorOrReadOnly extends BasePermission { message = 'Only the author can change this post.'
hasObjectPermission(request: APIRequest, _view: unknown, post: Post) { if (SAFE_METHODS.includes(request.method)) return true return post.authorId === request.user.pk }}Permission classes compose like DRF’s &, | and ~ operators through static helpers:
IsAuthorOrReadOnly.or(IsAdminUser) lets staff edit any post, and .and() and .not() work the
same way. Each returns a new permission class.
Routers
Section titled “Routers”A router generates URL patterns for a viewset. The project already has one: src/urls.ts
exports a DefaultRouter mounted at api/. Register the viewsets there:
import { admin } from '@ghuri/admin'import { include, path } from '@ghuri/core'import { DefaultRouter, ScalarView, SchemaView, SwaggerUIView } from '@ghuri/rest'import type { Context } from 'hono'import { PostViewSet, TagViewSet } from './blog/views'import { urlpatterns as blogUrls } from './blog/urls'
/** REST API router: register viewsets here, e.g. `router.register('posts', PostViewSet)`. */export const router = new DefaultRouter()router.register('posts', PostViewSet)router.register('tags', TagViewSet)
function home(c: Context) { return c.json({ project: 'mysite', admin: '/admin/', api: '/api/', docs: '/api/docs/' })}
export const urlpatterns = [ path('', home, { name: 'home' }), path('admin/', admin.site.urls), path('api/schema/', SchemaView.asView({ title: 'mysite API', version: '0.1.0' }), { name: 'schema' }), path('api/docs/', SwaggerUIView.asView({ urlName: 'schema' }), { name: 'swagger-ui' }), path('api/reference/', ScalarView.asView({ urlName: 'schema' }), { name: 'scalar' }), path('api/', include(router.urls)), path('blog/', include(blogUrls)),]You now have:
| URL | Name | Methods |
|---|---|---|
/api/ |
api-root |
GET (API root) |
/api/posts/ |
post-list |
GET, POST |
/api/posts/<slug>/ |
post-detail |
GET, PUT, PATCH, DELETE |
/api/posts/<slug>/publish/ |
post-publish |
POST |
/api/posts/<slug>/comments/ |
post-comments |
GET, POST |
/api/tags/, /api/tags/<pk>/ |
tag-list, tag-detail |
GET |
curl 'http://localhost:8787/api/posts/?search=ghuri&ordering=-createdAt'curl 'http://localhost:8787/api/posts/?tags__name=typescript'List responses are paginated by the project’s PageNumberPagination setting:
{ "count": …, "next": …, "previous": …, "results": [ … ] }. Open /api/posts/ in a browser
to get the browsable API.
Authentication
Section titled “Authentication”The generated settings already configure the REST framework for you:
REST_FRAMEWORK: { DEFAULT_AUTHENTICATION_CLASSES: [SessionAuthentication, TokenAuthentication], DEFAULT_PERMISSION_CLASSES: [IsAuthenticatedOrReadOnly], DEFAULT_PAGINATION_CLASS: PageNumberPagination, PAGE_SIZE: 20,},Browsers that are logged into the admin already have a session, so SessionAuthentication
works for them (and enforces CSRF on unsafe methods). Other clients send a token, stored by the
authtoken app (AuthTokenConfig, already in INSTALLED_APPS). Add an endpoint that exchanges
a username and password for a token:
import { obtainAuthToken } from '@ghuri/auth/rest'// ...
export const urlpatterns = [ path('', home, { name: 'home' }), path('admin/', admin.site.urls), // ...the three schema / docs routes path('api/', include(router.urls)), path('api-token-auth/', obtainAuthToken), path('blog/', include(blogUrls)),]obtainAuthToken is CSRF-exempt and expects JSON (or form data). Get a token and use it:
curl -X POST http://localhost:8787/api-token-auth/ \ -H 'Content-Type: application/json' \ -d '{"username": "rifat", "password": "correct horse"}'# {"token":"9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}
curl -X POST http://localhost:8787/api/posts/ \ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' \ -H 'Content-Type: application/json' \ -d '{"title": "Written over the API", "slug": "over-the-api", "tags": ["typescript"]}'The response is 201 Created with the serialized post, and authorName is rifat because
performCreate set the author from the request. You can also create a token from the command
line with npx ghuri drf_create_token rifat. If you prefer JWTs, use JWTAuthentication with
TokenObtainPairView and TokenRefreshView; see
REST authentication and
Auth tokens.
OpenAPI docs
Section titled “OpenAPI docs”The project came with an OpenAPI 3.1 schema and interactive docs; they are the three
api/schema/, api/docs/ and api/reference/ routes in src/urls.ts. Open
http://localhost:8787/api/docs/ for Swagger UI or http://localhost:8787/api/reference/ for
Scalar, and try every endpoint from the browser. The raw document is at /api/schema/. It is
built from your views and serializers, so it stays in sync with the code.
To write it to a file, for a client generator or to commit it:
npx ghuri generateschema --file openapi.yamlSee OpenAPI to rename operations, add tags or hide views.
Testing the API
Section titled “Testing the API”startapp created src/blog/tests.ts, whose test still expects the Part 1 index view. Replace
it with a test that exercises the API through the real middleware and URL stack:
import { afterAll, beforeAll, describe, expect, it } from 'vitest'import { createApp } from '@ghuri/core'import { createTestClient } from '@ghuri/core/testing'import { setupTestDatabase } from '@ghuri/orm/testing'import { User } from '@ghuri/auth'import settings from '../settings'import { Post } from './models'
// Use one env object everywhere: settings are resolved (and cached) per env object.const env = { SECRET_KEY: 'test', DEBUG: 'true' }const app = createApp(settings)let db: Awaited<ReturnType<typeof setupTestDatabase>>
beforeAll(async () => { await app.setup(env) db = await setupTestDatabase({ using: 'sqlite' }) // in-memory, runs every migration})afterAll(() => db.teardown())
describe('posts API', () => { it('hides drafts from anonymous users', async () => { const author = await User.objects.createUser({ username: 'a', password: 'pw-123456' }) await Post.objects.create({ title: 'Draft', slug: 'draft', author }) await Post.objects.create({ title: 'Live', slug: 'live', author, published: true })
const client = createTestClient(app, { env }) const res = await client.get('/api/posts/') expect(res.status).toBe(200) const body = await res.json() expect(body.results.map((p: { slug: string }) => p.slug)).toEqual(['live']) })})npx ghuri testThe generated vitest.config.ts picks up src/**/tests.ts and *.test.ts files, and turns on
oxc’s legacy decorator mode so @admin.register and @action load under Vitest (Ghuri’s
decorators work in both modes).
setupTestDatabase() swaps the default database for a fresh in-memory one ('sqlite',
'pglite' for Postgres, or 'd1' through Miniflare) and applies your migrations, so the test
never touches your development data. For DRF-style tests, APIClient from @ghuri/rest/testing
adds forceAuthenticate(user) and parsed res.data. More in Testing.
You have a complete backend. The last step is to put it on the internet: Part 5: Deploy to Cloudflare.