rest

@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