apiform

Auto-generate CRUD REST API routes from your Prisma schema — with consistent responses, pagination, search, and full customization.

---

What is apiform?

apiform sits on top of your existing Prisma setup and automatically generates a fully structured REST API from your models. No writing controllers. No repetitive route handlers. Just plug in your Prisma client and your API is ready.

Your Prisma Schema → apiform → Fully structured REST API

Every route returns a consistent, predictable response shape — making your API easier to consume and debug.

---

Features

• Auto-generated CRUD routes from your Prisma schema
• Consistent response shape across all endpoints
• Built-in pagination, search, sorting, and filtering on all GET list endpoints
• Soft delete support — automatic soft delete for models with deletedAt field
• Nested relations — include related models via ?include= query parameter
• TypeScript generics — fully typed responses out of the box
• Role-Based Access Control (RBAC) — global and per-route role protection
• Rate limiting — global and per-route rate limiting out of the box
• Fully customizable — disable routes, add middleware, change prefixes per model
• Custom routes — add your own routes on top of generated ones
• TypeScript first — full type safety and intellisense out of the box
• Fastify powered — fast and lightweight HTTP layer

---

Requirements

• Node.js >= 20
• Prisma >= 7.0.0
• TypeScript >= 5.0.0

---

Installation

npm install apiform
# or
bun add apiform

---

Quick Start

1. Set up your Prisma client (Prisma v7 requires an adapter):

import { PrismaClient } from "@prisma/client";
import { PrismaLibSql } from "@prisma/adapter-libsql";

const adapter = new PrismaLibSql({ url: "file:./prisma/dev.db" });
const prisma = new PrismaClient({ adapter });

2. Pass it to ApiForm and start the server:

import { ApiForm } from "apiform";

const app = new ApiForm(prisma, {
  globalPrefix: "/api",
  models: {
    user: true,
    post: true,
  },
});

app.start(3000);

That's it. Your API is running with the following routes auto-generated for each model:

Method	Route	Action
GET	/api/users	Find all (paginated)
GET	/api/users/:id	Find by ID
POST	/api/users	Create
PATCH	/api/users/:id	Update
DELETE	/api/users/:id	Delete

---

Response Shape

Every endpoint returns the same consistent structure:

Success (single record):

{
  "success": true,
  "message": "USER_CREATED_SUCCESSFULLY",
  "data": {},
  "meta": null,
  "error": null
}

Success (list):

{
  "success": true,
  "message": "USERS_RETRIEVED_SUCCESSFULLY",
  "data": [],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10,
    "hasNext": true,
    "hasPrev": false
  },
  "error": null
}

Error:

{
  "success": false,
  "message": "VALIDATION_ERROR",
  "data": null,
  "meta": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": []
  }
}

---

Pagination, Search & Filtering

All GET list endpoints support the following query parameters out of the box:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 10)
searchBy	string	Field name to search on
searchValue	string	Value to search for
sortBy	string	Field to sort by (default: createdAt)
sortOrder	asc or desc	Sort direction (default: desc)
filters	JSON string	Additional field filters

Example:

GET /api/users?page=2&limit=5&searchBy=name&searchValue=john&sortBy=createdAt&sortOrder=desc

---

Customization

Disable a specific route

const app = new ApiForm(prisma, {
  models: {
    user: {
      delete: { enabled: false },
    },
  },
});

Add middleware to a route

const app = new ApiForm(prisma, {
  models: {
    user: {
      findAll: {
        middleware: [authMiddleware],
      },
    },
  },
});

Custom route prefix per model

const app = new ApiForm(prisma, {
  models: {
    user: {
      prefix: "/members",
    },
  },
});
// Routes: GET /api/members, POST /api/members, etc.

Global middleware

const app = new ApiForm(prisma, {
  globalMiddleware: [loggingMiddleware, authMiddleware],
  models: {
    user: true,
  },
});

Disable an entire model

const app = new ApiForm(prisma, {
  models: {
    user: true,
    post: false, // no routes generated for Post
  },
});

Add custom routes

Use addRoutes() to add your own routes on top of the auto-generated ones. Custom routes are always registered after apiform's routes, so they won't be overwritten.

const app = new ApiForm(prisma, {
  globalPrefix: "/api",
  models: { user: true },
});

app.addRoutes((fastify) => {
  fastify.get("/api/users/count", async (request, reply) => {
    const count = await prisma.user.count();
    reply.send({
      success: true,
      message: "USERS_COUNTED_SUCCESSFULLY",
      data: { count },
      meta: null,
      error: null,
    });
  });
});

app.start(3000);

addRoutes() is chainable — you can call it multiple times:

app.addRoutes(userRoutes).addRoutes(postRoutes).start(3000);

Override a generated route

To override one of apiform's auto-generated routes, simply register the same method and path inside addRoutes(). Since custom routes are registered after apiform's routes, yours will take precedence:

app.addRoutes((fastify) => {
  // Overrides apiform's default GET /api/users
  fastify.get("/api/users", async (request, reply) => {
    // your custom implementation
  });
});

---

Soft Delete

Models with a deletedAt DateTime? field automatically use soft delete — records are never permanently deleted, just marked with a timestamp.

Add deletedAt to your Prisma model:

model User {
  id        Int       @id @default(autoincrement())
  name      String
  email     String    @unique
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?
}

Auto-generated soft delete routes:

Method	Route	Action
DELETE	/api/users/:id	Soft delete (sets deletedAt)
GET	/api/users/deleted	Find all soft deleted records
PATCH	/api/users/:id/restore	Restore a soft deleted record

Soft deleted records are automatically excluded from all GET list and findById queries.

Enable soft delete routes in config:

const app = new ApiForm(prisma, {
  models: {
    user: {
      findDeleted: { enabled: true },
      restore: { enabled: true },
    },
  },
});

Custom soft delete field name:

const app = new ApiForm(prisma, {
  models: {
    user: {
      softDelete: "deleted_at", // use custom field name
    },
  },
});

⚠️ Soft Delete & Relations

apiform does not prevent linking records to soft deleted related records. It is the developer's responsibility to ensure relation integrity via custom middleware, application-level validation, or Prisma's referential actions.

---

Role-Based Access Control (RBAC)

Protect your auto-generated routes with role-based access control. apiform checks the user's roles from the request and returns 403 FORBIDDEN if they don't have the required role.

Setup:

const app = new ApiForm(prisma, {
  rbac: {
    rolesPath: "user.roles", // where to find roles on the request (default: "user.roles")
    globalRoles: ["user"], // roles required for ALL routes
  },
  models: {
    user: {
      findAll: { roles: ["admin"] }, // override — only admin can list users
      delete: { roles: ["admin"] }, // override — only admin can delete
    },
  },
});

How it works:

• globalRoles applies to every route unless overridden
• Per-route roles overrides globalRoles for that specific route
• If no roles are configured, the route is public
• Roles are looked up from the request using rolesPath (supports dot notation e.g. auth.user.roles)

Custom roles path:

rbac: {
  rolesPath: "auth.roles",  // looks at request.auth.roles
}

Response when access is denied:

{
  "success": false,
  "message": "You do not have permission to access this resource",
  "data": null,
  "meta": null,
  "error": {
    "code": "FORBIDDEN"
  }
}

Note: apiform does not handle authentication — it only checks roles. You are responsible for populating request.user (or your custom path) via your own auth middleware before apiform's RBAC runs.

---

TypeScript Generics

All CRUD operations support TypeScript generics for fully typed responses:

import type { User } from "@prisma/client";

const result = await crud.findById<User>("user", 1);
result.data.email; // ✅ typed as string
result.data.name; // ✅ typed as string

const list = await crud.findAll<User>("user", {});
list.data; // ✅ typed as User[]

---

Nested Relations

Include related models in your queries using the ?include= query parameter:

GET /api/posts?include=author
GET /api/users/1?include=posts
GET /api/posts?include=author,comments

Example response with included relation:

{
  "success": true,
  "message": "POSTS_RETRIEVED_SUCCESSFULLY",
  "data": [
    {
      "id": 1,
      "title": "Hello World",
      "author": {
        "id": 1,
        "name": "John Doe"
      }
    }
  ],
  "meta": { ... },
  "error": null
}

---

Rate Limiting

Protect your API from abuse with built-in rate limiting powered by @fastify/rate-limit.

Global rate limit:

const app = new ApiForm(prisma, {
  rateLimit: {
    max: 100, // maximum requests
    timeWindow: 60, // per 60 seconds
  },
  models: {
    user: true,
  },
});

Per route override:

const app = new ApiForm(prisma, {
  rateLimit: {
    max: 100,
    timeWindow: 60,
  },
  models: {
    user: {
      create: { rateLimit: { max: 10, timeWindow: 60 } }, // stricter on create
    },
  },
});

Response when rate limit is exceeded:

{
  "success": false,
  "message": "RATE_LIMIT_EXCEEDED",
  "data": null,
  "meta": null,
  "error": {
    "code": "TOO_MANY_REQUESTS"
  }
}

Rate limit headers are automatically included in every response:

• x-ratelimit-limit — maximum requests allowed
• x-ratelimit-remaining — requests remaining in current window
• x-ratelimit-reset — seconds until the window resets

---

Configuration Reference

new ApiForm(prismaClient, {
  globalPrefix?: string;          // default: "/api"
  globalMiddleware?: Function[];   // runs before every route
  schemaPath?: string;            // custom path to schema.prisma
  rateLimit?: {
    max: number;                  // maximum requests
    timeWindow: number;           // time window in seconds
  };
  rbac?: {
    rolesPath?: string;           // default: "user.roles"
    globalRoles?: string[];       // roles required for all routes
  };
  models?: {
    [modelName]: boolean | {
      prefix?: string;
      softDelete?: boolean | string;
      create?: RouteOptions;
      findAll?: RouteOptions;
      findById?: RouteOptions;
      update?: RouteOptions;
      delete?: RouteOptions;
      restore?: RouteOptions;
      findDeleted?: RouteOptions;
    }
  }
});

// RouteOptions
{
  enabled?: boolean;        // default: true
  middleware?: Function[];  // route-level middleware
  roles?: string[];         // roles required for this route
  rateLimit?: {
    max: number;            // override global rate limit
    timeWindow: number;     // time window in seconds
  };
}

---

Error Codes

Code	Description
VALIDATION_ERROR	Request body failed validation
NOT_FOUND	Record not found
CONFLICT	Unique constraint violation
BAD_REQUEST	Invalid request
INTERNAL_ERROR	Unexpected server error
UNAUTHORIZED	Unauthorized access
FORBIDDEN	Forbidden access

---

License

MIT © Bibek Raj Ghimire