Apialize

Apialize transforms Sequelize database models into production-ready REST APIs with minimal configuration. Build complete CRUD endpoints with filtering, pagination, relationships, and hooks in just a few lines of code.

Installation

npm install apialize

What Does Apialize Do?

Apialize creates production-ready REST API endpoints directly from your Sequelize models with minimal code. Simply pass your model to an operation function, and you get a fully functional endpoint with extensive configuration options:

• Easy Setup: Transform models into API endpoints in a single line of code
• Flexible Configuration: Customize behavior with dozens of options for filtering, pagination, field control, and more
• Granular Control: Choose exactly which operations to expose for each resource
• Advanced Filtering: Query by any field with support for operators and predicates
• Relationship Handling: Automatically include related models and manage foreign keys
• Custom ID Fields: Use UUIDs or any field as resource identifiers
• Middleware Hooks: Add authentication, validation, and transformation logic at any point
• Field Mapping: Alias external API field names to internal database columns
• Nested Flattening: Flatten relationships into parent responses for cleaner APIs
• Complex Search: Build sophisticated queries with multiple filters and conditions

Quick Start

const express = require('express');
const { Sequelize, DataTypes } = require('sequelize');
const { list, single, create, update, patch, destroy } = require('apialize');

const sequelize = new Sequelize('sqlite::memory:');
const User = sequelize.define('User', {
  id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true },
  name: { type: DataTypes.STRING, allowNull: false },
  email: { type: DataTypes.STRING, allowNull: false },
});

await sequelize.sync();

const app = express();
app.use(express.json());

// Mount individual operations with full control
app.use('/users', list(User));
app.use('/users', single(User));
app.use('/users', create(User));
app.use('/users', patch(User));
app.use('/users', destroy(User));

app.listen(3000);

Each operation gives you precise control over your API endpoints!

Available Operations & Endpoints

Apialize provides individual operation functions that give you precise control over which endpoints to expose.

| Operation | HTTP Method & Endpoint | Description | Documentation | | ----------- | ------------------------- | -------------------------------------------------------- | --------------------------------------------------- | | list | GET /resource | List all records with filtering, sorting, and pagination | List Documentation | | single | GET /resource/:id | Get a single record by ID | Single Documentation | | create | POST /resource | Create a new record | Create Documentation | | update | PUT /resource/:id | Replace a record (full update) | Update Documentation | | patch | PATCH /resource/:id | Partially update a record | Patch Documentation | | destroy | DELETE /resource/:id | Delete a record | Destroy Documentation | | search | POST /resource/search | Advanced search with complex filters | Search Documentation | | action | POST /resource/:id/verb | Custom domain verb sharing the full CRUD lifecycle | Actions Documentation |

Using Individual Operations

const {
  list,
  single,
  create,
  update,
  patch,
  destroy,
  search,
} = require('apialize');

// Mount only the operations you need
app.use('/users', list(User)); // GET /users
app.use('/users', single(User)); // GET /users/:id
app.use('/users', create(User)); // POST /users
app.use('/users', update(User)); // PUT /users/:id
app.use('/users', patch(User)); // PATCH /users/:id
app.use('/users', destroy(User)); // DELETE /users/:id
app.use('/users', search(User)); // POST /users/search

Configuration Options

Apialize accepts two types of configuration: Apialize Options and Model Options.

Apialize Options

Configure Apialize-specific behaviors:

| Option | Type | Description | Applies To | | --------------------- | ------ | ------------------------------------------------ | ------------------------------ | | id_mapping | string | Use a different field as the resource identifier | single, update, patch, destroy | | middleware | array | Custom middleware functions for hooks | All operations | | default_page_size | number | Default number of records per page | list, search | | allow_filtering_on | array | Fields that can be used in filters | list, search | | allow_ordering_on | array | Fields that can be used for sorting | list, search | | relation_id_mapping | object | Map relationship IDs to custom fields | create, update, patch | | field_aliases | object | Map external field names to database columns | All operations |

Model Options

Standard Sequelize query options:

| Option | Type | Description | Applies To | | ------------ | ------ | --------------------------------- | --------------------- | | attributes | array | Control which fields are returned | list, single, search | | fields | array | Control which fields can be set | create, update, patch | | include | array | Include related models | list, single, search | | where | object | Apply fixed filters | list, search | | scope | string | Use a Sequelize scope | All operations |

Example: Combined Configuration

app.use(
  '/items',
  list(
    Item,
    // Apialize options
    {
      middleware: [authMiddleware],
      default_page_size: 25,
      allow_filtering_on: ['category', 'status'],
      allow_ordering_on: ['created_at', 'name'],
    },
    // Model options
    {
      attributes: ['id', 'name', 'category', 'status'],
      include: [{ model: User, as: 'owner' }],
    }
  )
);

Common Use Cases

Authentication & Scoping

Automatically scope queries to the current user:

const scopeToUser = (req, res, next) => {
  req.apialize.apply_where({ user_id: req.user.id });
  next();
};

app.use('/items', list(Item, { middleware: [scopeToUser] }));

Custom ID Fields

Use UUIDs or external IDs instead of auto-increment IDs:

app.use('/users', single(User, { id_mapping: 'external_id' }));
// Access: GET /users/uuid-abc-123

Field Aliases

Map external API field names to database columns:

app.use(
  '/users',
  list(User, {
    field_aliases: {
      external_name: 'name',
      user_email: 'email',
    },
  })
);
// Query: GET /users?external_name=John

Including Relationships

Automatically include related models:

app.use(
  '/posts',
  list(
    Post,
    {},
    {
      include: [
        { model: User, as: 'author' },
        { model: Comment, as: 'comments' },
      ],
    }
  )
);

Relationship ID Mapping

Allow setting relationships by custom ID fields:

app.use(
  '/posts',
  create(Post, {
    relation_id_mapping: {
      author: 'external_id',
    },
  })
);
// POST /posts { "author_id": "uuid-123", ... }

Advanced Features

For detailed information on advanced features, see the full documentation:

• Authorization: Gate access to each call with an authorize function
• Hooks & Middleware: Add custom logic before and after operations
• Filtering: Complex query filters and operators
• Flattening: Flatten nested relationships into parent responses
• Custom Serialization of Results: Reshape each record or replace the whole response envelope
• Field Aliases: Map external to internal field names
• Relation ID Mapping: Use custom fields for relationships
• createApialize: Share application-wide default options across a single apialize object
• Model Configuration: Configure default behaviors per model
• Context Helpers: Utilities for middleware and hooks
• Actions: First-class custom verbs (e.g. POST /orders/:id/pay) with authorize, scoped load, transaction, hooks, transition guards, and serialization
• Single Member Routes: Custom routes for single resources
• Single Related Models: Access related resources directly
• OpenAPI Generation: Auto-generate an OpenAPI 3.1 spec for Swagger UI, codegen pipelines, and OpenAI Custom GPTs

License

MIT

Repository

https://github.com/andrewsinnovations/apialize

Complete Documentation Reference

Core Operations

• index.md - Overview and introduction
• crud.md - Complete CRUD operations (all endpoints at once)
• list.md - List operation (GET collection)
• single.md - Single record retrieval (GET by ID)
• create.md - Create operation (POST)
• update.md - Update operation (PUT - full replace)
• patch.md - Patch operation (PATCH - partial update)
• destroy.md - Delete operation (DELETE)
• search.md - Advanced search (POST with filters)
• actions.md - Custom verbs sharing the CRUD lifecycle

Advanced Features

• filtering.md - Query filtering and operators
• authorization.md - Gate access to each call
• hooks.md - Middleware and lifecycle hooks
• aliasing.md - Field name aliasing
• flattening.md - Flatten nested relationships
• serialization.md - Custom serialization of results
• relation_id_mapping.md - Custom relationship identifiers
• create_apialize.md - Application-wide default options via createApialize
• model_configuration.md - Per-model default configuration
• context_helpers.md - Request context utilities
• single_member_routes.md - Custom single resource routes
• single_related_models.md - Direct access to related resources
• openapi.md - OpenAPI 3.1 spec generation, Swagger UI, Custom GPTs