|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +sidebar_label: Custom |
| 4 | +title: Custom API Handler |
| 5 | +description: Extend or implement ZenStack API handlers to match your backend conventions. |
| 6 | +--- |
| 7 | + |
| 8 | +# Custom API Handler |
| 9 | + |
| 10 | +## Overview |
| 11 | + |
| 12 | +ZenStack ships ready-to-use REST and RPC handlers, but you can tailor their behavior or author brand new handlers without leaving TypeScript. The server package exposes the handler contracts through `@zenstackhq/server/types`, utility helpers from `@zenstackhq/server/api`, all built-in handlers expose their methods as `protected` to allow for extension points. You can: |
| 13 | + |
| 14 | +- override parts of the REST or RPC pipeline (filtering, serialization, validation, error handling, and more); |
| 15 | +- wrap the default handlers with extra behavior (multi-tenancy, telemetry, custom logging); |
| 16 | +- implement a handler from scratch while still benefiting from ZenStack's schema and serialization helpers. |
| 17 | + |
| 18 | +## Core building blocks |
| 19 | + |
| 20 | +```ts |
| 21 | +import { |
| 22 | + type ApiHandler, |
| 23 | + type RequestContext, |
| 24 | + type Response, |
| 25 | + type LogConfig, |
| 26 | +} from '@zenstackhq/server/types'; |
| 27 | +import { registerCustomSerializers, getZodErrorMessage, log } from '@zenstackhq/server/api'; |
| 28 | +``` |
| 29 | + |
| 30 | +- `ApiHandler`, `RequestContext`, and `Response` define the framework-agnostic contract used by every server adapter. |
| 31 | +- `LogConfig` (and the related `Logger` type) mirrors the handler `log` option so you can surface diagnostics consistently. |
| 32 | +- `registerCustomSerializers` installs the Decimal/Bytes superjson codecs that power the built-in handlers—call it once when implementing your own handler. |
| 33 | +- `getZodErrorMessage` and `log` help you align error formatting and logging with the defaults. |
| 34 | + |
| 35 | +## Extending the REST handler |
| 36 | + |
| 37 | +The REST handler exposes its internals (for example `buildFilter`, `processRequestBody`, `handleGenericError`, and serializer helpers) as `protected`, so subclasses can tweak individual steps without re-implementing the whole pipeline. |
| 38 | + |
| 39 | +```ts |
| 40 | +import { RestApiHandler, type RestApiHandlerOptions } from '@zenstackhq/server/api'; |
| 41 | +import { schema } from '~/zenstack/schema'; |
| 42 | + |
| 43 | +type Schema = typeof schema; |
| 44 | + |
| 45 | +class PublishedOnlyRestHandler extends RestApiHandler<Schema> { |
| 46 | + constructor(options: RestApiHandlerOptions<Schema>) { |
| 47 | + super(options); |
| 48 | + } |
| 49 | + |
| 50 | + protected override buildFilter(type: string, query: Record<string, string | string[]> | undefined) { |
| 51 | + const base = super.buildFilter(type, query); |
| 52 | + if (type !== 'post') { |
| 53 | + return base; |
| 54 | + } |
| 55 | + |
| 56 | + const existing = |
| 57 | + base.filter && typeof base.filter === 'object' && !Array.isArray(base.filter) |
| 58 | + ? { ...(base.filter as Record<string, unknown>) } |
| 59 | + : {}; |
| 60 | + |
| 61 | + return { |
| 62 | + ...base, |
| 63 | + filter: { |
| 64 | + ...existing, |
| 65 | + published: true, |
| 66 | + }, |
| 67 | + }; |
| 68 | + } |
| 69 | +} |
| 70 | + |
| 71 | +export const handler = new PublishedOnlyRestHandler({ |
| 72 | + schema, |
| 73 | + endpoint: 'https://api.example.com', |
| 74 | +}); |
| 75 | +``` |
| 76 | + |
| 77 | +The override inserts a default `published` filter for the `post` collection while delegating everything else to the base class. You can apply the same pattern to other extension points, such as: |
| 78 | + |
| 79 | +- `processRequestBody` to accept additional payload metadata; |
| 80 | +- `handleGenericError` to hook into your observability pipeline; |
| 81 | +- `buildRelationSelect`, `buildSort`, or `includeRelationshipIds` to expose bespoke query features. |
| 82 | + |
| 83 | +Refer back to the [RESTful API Handler](./rest) page for the canonical behavior and extension points. |
| 84 | + |
| 85 | +## Extending the RPC handler |
| 86 | + |
| 87 | +`RPCApiHandler` exposes similar `protected` hooks. Overriding `unmarshalQ` lets you accept alternative encodings for the `q` parameter, while still benefiting from the built-in JSON/SuperJSON handling. |
| 88 | + |
| 89 | +```ts |
| 90 | +import { RPCApiHandler, type RPCApiHandlerOptions } from '@zenstackhq/server/api'; |
| 91 | +import { schema } from '~/zenstack/schema'; |
| 92 | + |
| 93 | +type Schema = typeof schema; |
| 94 | + |
| 95 | +class Base64QueryHandler extends RPCApiHandler<Schema> { |
| 96 | + constructor(options: RPCApiHandlerOptions<Schema>) { |
| 97 | + super(options); |
| 98 | + } |
| 99 | + |
| 100 | + protected override unmarshalQ(value: string, meta: string | undefined) { |
| 101 | + if (value.startsWith('base64:')) { |
| 102 | + const decoded = Buffer.from(value.slice('base64:'.length), 'base64').toString('utf8'); |
| 103 | + return super.unmarshalQ(decoded, meta); |
| 104 | + } |
| 105 | + return super.unmarshalQ(value, meta); |
| 106 | + } |
| 107 | +} |
| 108 | + |
| 109 | +export const handler = new Base64QueryHandler({ schema }); |
| 110 | +``` |
| 111 | + |
| 112 | +The example uses Node's `Buffer` utility to decode the payload; adapt the decoding logic if you target an edge runtime. |
| 113 | + |
| 114 | +Other useful hooks include: |
| 115 | + |
| 116 | +- `processRequestPayload` for enforcing per-request invariants (for example, injecting tenant IDs); |
| 117 | +- `makeBadInputErrorResponse`, `makeGenericErrorResponse`, and `makeORMErrorResponse` for customizing the error shape; |
| 118 | +- `isValidModel` if you expose a restricted subset of models to a specific client. |
| 119 | + |
| 120 | +Refer back to the [RPC API Handler](./rpc) page for the canonical behavior and endpoint matrix. |
| 121 | + |
| 122 | +## Implementing a handler from scratch |
| 123 | + |
| 124 | +When the built-in handlers are not a fit, implement the `ApiHandler` interface directly. Remember to call `registerCustomSerializers()` once so your handler understands Decimal and Bytes payloads the same way the rest of the stack does. |
| 125 | + |
| 126 | +```ts |
| 127 | +import type { ApiHandler, RequestContext, Response } from '@zenstackhq/server/types'; |
| 128 | +import { registerCustomSerializers } from '@zenstackhq/server/api'; |
| 129 | +import { schema } from '~/zenstack/schema'; |
| 130 | + |
| 131 | +type Schema = typeof schema; |
| 132 | + |
| 133 | +registerCustomSerializers(); |
| 134 | + |
| 135 | +class HealthcheckHandler implements ApiHandler<Schema> { |
| 136 | + constructor(private readonly logLevel: 'info' | 'debug' = 'info') {} |
| 137 | + |
| 138 | + get schema(): Schema { |
| 139 | + return schema; |
| 140 | + } |
| 141 | + |
| 142 | + get log() { |
| 143 | + return undefined; |
| 144 | + } |
| 145 | + |
| 146 | + async handleRequest({ method }: RequestContext<Schema>): Promise<Response> { |
| 147 | + if (method.toUpperCase() !== 'GET') { |
| 148 | + return { status: 405, body: { error: 'Only GET is supported' } }; |
| 149 | + } |
| 150 | + return { status: 200, body: { data: { status: 'ok', timestamp: Date.now() } } }; |
| 151 | + } |
| 152 | +} |
| 153 | + |
| 154 | +export const handler = new HealthcheckHandler(); |
| 155 | +``` |
| 156 | + |
| 157 | +## Plugging a custom handler into your app |
| 158 | + |
| 159 | +Custom handlers are consumed exactly like the built-in ones—hand them to any server adapter through the shared `apiHandler` option. |
| 160 | + |
| 161 | +```ts |
| 162 | +import { ZenStackMiddleware } from '@zenstackhq/server/express'; |
| 163 | +import { PublishedOnlyRestHandler } from './handler'; |
| 164 | +import { getClientFromRequest } from './auth'; |
| 165 | + |
| 166 | +app.use( |
| 167 | + '/api', |
| 168 | + ZenStackMiddleware({ |
| 169 | + apiHandler: new PublishedOnlyRestHandler({ schema, endpoint: 'https://api.example.com' }), |
| 170 | + getClient: getClientFromRequest, |
| 171 | + }) |
| 172 | +); |
| 173 | +``` |
| 174 | + |
| 175 | +For adapter-level customization strategies, head over to [Custom Server Adapter](../../reference/server-adapters/custom). |
0 commit comments