@objectstack/rest

Auto-generated REST API layer for ObjectStack — turns protocol metadata into CRUD, batch, metadata, and discovery endpoints with zero boilerplate.

Overview

@objectstack/rest is registered as a kernel plugin and emits HTTP routes for every object defined in the protocol metadata. Framework adapters (@objectstack/express, hono, fastify, nextjs, nuxt, nestjs, sveltekit) invoke these routes through HttpDispatcher from @objectstack/runtime.

Installation

pnpm add @objectstack/rest

Quick Start

import { ObjectKernel } from '@objectstack/core';
import { createRestApiPlugin } from '@objectstack/rest';

const kernel = new ObjectKernel();

kernel.use(createRestApiPlugin({
  api: {
    version: 'v1',
    basePath: '/api',
  },
}));

await kernel.bootstrap();

Standalone RestServer

import { RestServer } from '@objectstack/rest';

const server = new RestServer(protocol, config);
server.registerRoutes(dispatcher);

Custom routes via RouteManager

import { RouteManager } from '@objectstack/rest';

const routes = new RouteManager();
routes.register({ method: 'GET', path: '/custom', handler });

Generated endpoints

For every object Project defined in metadata, the plugin exposes:

| Method | Path | Purpose | |:---|:---|:---| | GET | /api/v1/projects | List with filter, sort, top, skip, select, groupBy, aggregations. | | GET | /api/v1/projects/:id | Single record (with ETag / Last-Modified). | | POST | /api/v1/projects | Create. | | PATCH | /api/v1/projects/:id | Partial update. | | PUT | /api/v1/projects/:id | Full replacement. | | DELETE | /api/v1/projects/:id | Delete. | | POST | /api/v1/projects/createMany | Batch create. | | POST | /api/v1/projects/updateMany | Batch update. | | POST | /api/v1/projects/deleteMany | Batch delete. | | POST | /api/v1/projects/batch | Mixed batch. |

Plus metadata and discovery routes:

| Path | Description | |:---|:---| | /api/v1/meta | All metadata types. | | /api/v1/meta/:type | Objects, views, apps, flows, agents, tools, translations. | | /api/v1/meta/:type/:name | Single metadata resource. | | /api/v1 and /.well-known/objectstack | Discovery / service manifest. |

Key Exports

| Export | Kind | Description | |:---|:---|:---| | createRestApiPlugin(config) | function | Kernel plugin factory. | | RestApiPluginConfig | type | { api: { version, basePath }, ... }. | | RestServer | class | Direct instantiation for adapters that need it. | | RouteManager, RouteGroupBuilder | classes | Register and group custom routes. | | RouteEntry | type | Route definition shape. |

Configuration

| Option | Type | Default | Notes | |:---|:---|:---|:---| | api.version | string | 'v1' | Embedded in the route prefix. | | api.basePath | string | '/api' | Root path for the API. | | paths.pathTransform | 'plural' \| 'kebab' \| 'camel' | 'plural' | Object → URL segment transform. | | caching.etag | boolean | true | Emits ETag header. | | caching.lastModified | boolean | true | Emits Last-Modified. |

HTTP semantics

• JSON envelope: { success, data, error?, meta? }.
• Validation errors: HTTP 400 with Zod issue list.
• Auth/permission failures: HTTP 401/403 emitted by @objectstack/plugin-auth and @objectstack/plugin-security.
• If-None-Match / If-Modified-Since honored for GET.

When to use

• ✅ Every runtime that exposes ObjectStack data over HTTP.

When not to use

• ❌ RPC-only or GraphQL-only deployments — use a custom @objectstack/runtime consumer.

Related Packages

• @objectstack/runtime — HttpDispatcher that invokes routes.
• Framework adapters under packages/adapters/*.

Links

• 📖 Docs: https://objectstack.ai/docs
• 📚 API Reference: https://objectstack.ai/docs/references/api
• 🤖 Skill: skills/objectstack-api/SKILL.md

License

Apache-2.0 © ObjectStack