REST framework
@ghuri/rest is a port of Django REST framework
(DRF). It gives you serializers that validate input and render output, class-based API views
and viewsets, routers that generate URL patterns, and the policies around them: permissions,
authentication, pagination, filtering, throttling and an OpenAPI 3.1 schema.
Everything is built on the same pieces as the rest of Ghuri. Serializers read your model’s
_meta to build their fields, viewsets run QuerySets through the ORM, and routers return plain
UrlPatterns that you include() in urls.ts.
Quick start
Section titled “Quick start”This builds a read-write API for the tutorial blog’s Post model. It assumes the blog app
from the tutorial is installed.
1. Write a serializer. A ModelSerializer derives its fields from the model.
import { ModelSerializer, StringRelatedField } from '@ghuri/rest'import { Post } from './models'
export class PostSerializer extends ModelSerializer<Post> { static Meta = { model: Post, fields: ['id', 'title', 'slug', 'body', 'published', 'author', 'tags', 'createdAt'], readOnlyFields: ['author', 'createdAt'], } author = new StringRelatedField()}2. Write a viewset. ModelViewSet provides list, create, retrieve, update, partial update
and destroy.
import { ModelViewSet, IsAuthenticatedOrReadOnly } from '@ghuri/rest'import { Post } from './models'import { PostSerializer } from './serializers'
export class PostViewSet extends ModelViewSet<Post> { queryset = Post.objects.selectRelated('author').prefetchRelated('tags') serializerClass = PostSerializer permissionClasses = [IsAuthenticatedOrReadOnly]
async performCreate(serializer: PostSerializer) { await serializer.save({ author: this.request.user }) }}3. Register it with a router and include the router’s URLs.
import { include, path } from '@ghuri/core'import { DefaultRouter } from '@ghuri/rest'import { PostViewSet } from './views'
const router = new DefaultRouter()router.register('posts', PostViewSet)
export const urlpatterns = [path('api/', include(router.urls))]That gives you:
| Method and path | Action |
|---|---|
GET /api/ |
API root listing the registered endpoints |
GET /api/posts/ |
list |
POST /api/posts/ |
create |
GET /api/posts/<pk>/ |
retrieve |
PUT /api/posts/<pk>/ |
update |
PATCH /api/posts/<pk>/ |
partialUpdate |
DELETE /api/posts/<pk>/ |
destroy |
Try it:
curl http://localhost:8787/api/posts/curl -X POST http://localhost:8787/api/posts/ \ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' \ -H 'Content-Type: application/json' \ -d '{"title": "Hello", "slug": "hello", "body": "First post"}'The Token header works once TokenAuthentication is listed in
DEFAULT_AUTHENTICATION_CLASSES (below); the default,
MiddlewareAuthentication, only sees session users.
How a request flows
Section titled “How a request flows”When a request reaches an API view, @ghuri/rest runs these steps in order, the same way DRF
does:
- Parse. The body is parsed according to
Content-Type(JSON, form or multipart) before your handler runs, sothis.request.datais a plain synchronous property. A parse error (ParseError400,UnsupportedMediaType415) is raised when you first read it, as in DRF. Query parameters are onthis.request.query(first value per key) andthis.request.queryParams(aURLSearchParams). - Negotiate content. The renderer is chosen from
Accept(JSON, or the browsable API for browsers). - Authenticate. Each class in
authenticationClassesis tried in turn. The first one that returns a user setsthis.request.user; if none does, the user is anonymous. - Check permissions. Every class in
permissionClassesmust allow the request. Object-level checks run later, whengetObject()loads the instance. - Throttle. Each class in
throttleClassesmay reject the request with429. - Dispatch to the handler (
get,post, …, or a viewset action such aslist). - Handle exceptions.
APIExceptionsubclasses, Ghuri’sHttp404/PermissionDenied/ValidationErrorand the ORM’sDoesNotExistare turned into JSON responses with DRF’s error shapes. Replace the handler withREST_FRAMEWORK.EXCEPTION_HANDLER.
Error responses
Section titled “Error responses”Errors use the shapes DRF clients already expect:
// 400 from a serializer{ "title": ["This field is required."], "slug": ["post with this slug already exists."] }
// 401, 403, 404, 405, 429{ "detail": "Authentication credentials were not provided." }Raise them yourself with the exception classes from @ghuri/rest: APIException,
ValidationError, ParseError, NotAuthenticated, AuthenticationFailed,
PermissionDenied, NotFound, MethodNotAllowed, NotAcceptable, UnsupportedMediaType and
Throttled.
import { APIException } from '@ghuri/rest'
export class ServiceUnavailable extends APIException { static statusCode = 503 static defaultDetail = 'Service temporarily unavailable, try again later.' static defaultCode = 'service_unavailable'}The REST_FRAMEWORK setting
Section titled “The REST_FRAMEWORK setting”Project-wide defaults live under one settings key. Any view can override them with its own attributes.
import { SessionAuthentication, TokenAuthentication } from '@ghuri/auth/rest'import { IsAuthenticatedOrReadOnly, PageNumberPagination, FieldFilter, SearchFilter, OrderingFilter, AnonRateThrottle, UserRateThrottle,} from '@ghuri/rest'
export default defineSettings((env) => ({ // ... REST_FRAMEWORK: { DEFAULT_AUTHENTICATION_CLASSES: [SessionAuthentication, TokenAuthentication], DEFAULT_PERMISSION_CLASSES: [IsAuthenticatedOrReadOnly], DEFAULT_PAGINATION_CLASS: PageNumberPagination, PAGE_SIZE: 20, DEFAULT_FILTER_BACKENDS: [FieldFilter, SearchFilter, OrderingFilter], DEFAULT_THROTTLE_CLASSES: [AnonRateThrottle, UserRateThrottle], DEFAULT_THROTTLE_RATES: { anon: '100/hour', user: '1000/day' }, },}))| Key | Default | Purpose |
|---|---|---|
DEFAULT_AUTHENTICATION_CLASSES |
[MiddlewareAuthentication] |
How request.user is determined |
DEFAULT_PERMISSION_CLASSES |
[AllowAny] |
Who may call a view |
DEFAULT_RENDERER_CLASSES |
[JSONRenderer, BrowsableAPIRenderer] |
Response formats |
DEFAULT_PARSER_CLASSES |
[JSONParser, FormParser, MultiPartParser] |
Accepted request bodies |
DEFAULT_CONTENT_NEGOTIATION_CLASS |
DefaultContentNegotiation |
Picks the renderer |
DEFAULT_METADATA_CLASS |
SimpleMetadata |
Body of OPTIONS responses |
DEFAULT_PAGINATION_CLASS |
null (no pagination) |
How list responses are paged |
PAGE_SIZE |
null |
Page size for the default paginator |
DEFAULT_FILTER_BACKENDS |
[] |
Backends applied in filterQueryset() |
DEFAULT_THROTTLE_CLASSES |
[] |
Rate limits applied to every view |
DEFAULT_THROTTLE_RATES |
{ user: null, anon: null } |
Rates per scope, e.g. { anon: '100/day' } |
THROTTLE_CACHE |
'default' |
Cache alias that stores throttle history |
NUM_PROXIES |
null |
Trusted proxies in front of the app, for client IPs |
DEFAULT_SCHEMA_CLASS |
AutoSchema |
OpenAPI schema per view |
SEARCH_PARAM |
'search' |
Query parameter for SearchFilter |
ORDERING_PARAM |
'ordering' |
Query parameter for OrderingFilter |
EXCEPTION_HANDLER |
exceptionHandler |
Turns exceptions into responses |
NON_FIELD_ERRORS_KEY |
'nonFieldErrors' |
Key for errors raised from validate() |
UNAUTHENTICATED_USER |
() => new AnonymousUser() |
User used when nobody authenticated |
UNAUTHENTICATED_TOKEN |
null |
request.auth when nobody authenticated |
URL_FORMAT_OVERRIDE / FORMAT_SUFFIX_KWARG |
'format' / 'format' |
?format=json and .json suffixes |
URL_FIELD_NAME |
'url' |
Name of HyperlinkedModelSerializer’s URL field |
DATETIME_FORMAT / DATE_FORMAT / TIME_FORMAT |
'iso-8601' |
Output formats |
COERCE_DECIMAL_TO_STRING |
true |
Render decimals as strings |
UPLOADED_FILES_USE_URL |
true |
Render file fields as URLs |
TEST_REQUEST_DEFAULT_FORMAT |
'multipart' |
Body format of APIClient requests |
Class references are classes, not dotted strings. That is how the bundler sees them and why your
editor can jump to them. Settings are read at request time through apiSettings (DRF’s
api_settings), so apiSettings.PAGE_SIZE works anywhere.
MiddlewareAuthentication uses the user that AuthenticationMiddleware already put on the
request and enforces CSRF on unsafe methods. For tokens or JWTs, list the classes from
@ghuri/auth/rest.
status holds DRF’s constants and helpers: status.HTTP_201_CREATED, status.isSuccess(code).
Testing an API
Section titled “Testing an API”APIClient from @ghuri/rest/testing is DRF’s test client: it encodes bodies, can skip
authentication, and parses JSON responses into res.data.
import { APIClient } from '@ghuri/rest/testing'
const client = new APIClient(app, { env, defaultFormat: 'json' })client.forceAuthenticate(user) // bypass the authentication classesclient.credentials({ Authorization: 'Token abc' }) // headers for every requestconst res = await client.post('/api/posts/', { title: 'Hi', slug: 'hi' })expect(res.status).toBe(201)expect(res.data.title).toBe('Hi')await client.get('/api/posts/', { search: 'hi' }) // second argument: query parametersUse the same env object for app.setup(env), setupTestDatabase() and the client so requests
see the test database. Formats are 'json', 'multipart' (the default,
TEST_REQUEST_DEFAULT_FORMAT) and 'form'. See Testing for the rest of
the test setup.
Where to go next
Section titled “Where to go next”- Serializers: validation, nested data, custom fields.
- Views and viewsets:
APIView, generics, mixins,@action. - Routers: URL generation and the API root.
- Permissions and authentication.
- Pagination, filtering and throttling.
- OpenAPI: schema generation, Swagger UI and Scalar.