From 5840667ae57ceac691159a5c538e4fdc2c202587 Mon Sep 17 00:00:00 2001 From: Abhishek Chatterjee Date: Sun, 26 Jul 2026 22:34:11 +0530 Subject: [PATCH] chore(readme): ROSS-187: updated the project README --- README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 127 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 2d9bd17..c231b03 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,21 @@ Rocket API Framework Logo

-Rocket is a configuration-driven API framework designed to accelerate backend development by automating standard engineering tasks. By defining models in a structured JSON format, Rocket automatically handles database schema generation, RESTful routing, request validation, and interactive documentation. +Rocket is a configuration-driven API framework designed to accelerate backend development by automating standard engineering tasks. By defining models in a structured JSON format, Rocket automatically handles database schema generation, RESTful routing, authentication, request validation, and interactive documentation. ## Features -- **Automated API Generation**: Instant creation of CRUD, Search, and Aggregate endpoints from JSON configurations. -- **Database Schema Management**: Automatic handling of table creation, multi-column indexes, and foreign key constraints. -- **Multi-Engine Database Support**: Native support for both PostgreSQL and SQLite. -- **Interactive Documentation**: Integrated Swagger/OpenAPI UI available at the specified documented path. -- **Robust Validation**: Driven by AJV (JSON Schema) for strict and customizable request validation. -- **Advanced Querying**: Native support for filtering, sorting, and complex search operations. +- **Automated API Generation**: Instant creation of CRUD, Search, Index, and Aggregate endpoints from JSON configurations. +- **Database Schema Management**: Automatic handling of table creation, relations, multi-column indexes, and foreign key constraints. +- **Multi-Engine Database Support**: Native support for PostgreSQL and SQLite. +- **Built-in Authentication**: JWT-based authentication with registration, login, password reset, and optional MFA. +- **Caching Layer**: Redis integration for high-performance caching. +- **Rate Limiting**: Configurable request rate limiting with cache-backed storage. +- **Webhooks**: Per-API webhook triggers for request/response events. +- **Custom Endpoints**: SQL-based custom endpoints with parameterized queries. +- **Interactive Documentation**: Integrated Swagger/OpenAPI UI. +- **Robust Validation**: AJV-powered JSON Schema validation for all requests. +- **Advanced Querying**: Filtering, sorting, aggregations, and full-text search. ## Quick Start @@ -42,51 +47,143 @@ Once the server is initialized, refer to the Swagger UI for interactive API docu ## Configuration -Rocket utilizes a `config.json` file for system orchestration. Below is an overview of the primary configuration blocks: +Rocket uses a `config.json` file for system orchestration. Below is a minimal configuration example: ```json { - "swagger": { - "enabled": true, - "basePath": "/api/docs", - "info": { "title": "Rocket API", "version": "1.0.0" } + "application": { + "name": "Rocket OSS", + "logLevel": "info", + "rateLimit": { + "enabled": true, + "max": 1000, + "timeWindow": "15m" + } + }, + "docs": { + "openapi": { + "enabled": true, + "path": "/api/docs", + "info": { + "title": "Rocket API", + "version": "1.0.0" + } + } }, - "database": { - "engine": "sqlite", - "connection": { "urlOrPath": "./database.db" } + "infrastructure": { + "database": { + "engine": "sqlite", + "connection": { "url": "./database.db" } + }, + "cache": { + "engine": "redis", + "connection": { "url": "redis://localhost:6379" } + } }, - "models": [ - { - "name": "users", - "fields": [ - { "name": "id", "type": "integer", "primaryKey": true }, - { "name": "email", "type": "string", "unique": true, "supportedOperations": ["searchable", "equal", "sortable"] } - ] + "authentication": { + "enabled": true, + "provider": { + "type": "up-auth", + "config": { + "userModel": { + "model": "users", + "idField": "id", + "usernameField": "email", + "passwordField": "password" + }, + "jwtSecret": "your-secret-key", + "mfaRequired": false + } } - ] + }, + "data": { + "models": { + "users": { + "timestamps": true, + "fields": { + "id": { + "type": "integer", + "primaryKey": true, + "autoIncrement": true, + "apis": ["index", "edit", "delete"] + }, + "email": { + "type": "string", + "unique": true, + "nullable": false, + "apis": ["search", "index"], + "query": ["eq", "sort"] + }, + "name": { + "type": "string", + "nullable": true, + "query": ["sort"] + } + } + } + } + } } ``` -### Field Operations +### Field Configuration + +Each field supports granular control over API capabilities: + +**APIs** - Controls which endpoints expose the field: +- `search`: Full-text search endpoint +- `index`: Get by primary key endpoint +- `edit`: Update endpoint +- `delete`: Delete endpoint + +**Query Operations** - Filtering and sorting capabilities: +- `eq`, `ne`: Equality/inequality filters +- `lt`, `lte`, `gt`, `gte`: Comparison filters +- `in`, `not_in`: Array membership filters +- `sort`: Enable sorting by this field -Specific operations can be enabled per field to control API exposure: +**Aggregations** - Data aggregation functions: +- `count`, `avg`, `sum`, `min`, `max`, `frequency` -- `searchable`: Enables full-text search capabilities on the specific field. -- `equal`, `greaterThan`, `oneOf`: Provides granular filtering options. -- `sortable`: Permits sorting based on the field values. +### Advanced Features + +**Relations**: Define foreign key relationships between models with cascade actions (`belongsTo`). + +**Custom Endpoints**: Execute parameterized SQL queries via custom HTTP endpoints. + +**Webhooks**: Configure per-API webhooks that trigger on request/response with customizable payloads. + +**Server-Side Parameters**: Inject server-controlled parameters into API requests for enhanced security. + +See `example_config.json` for a complete configuration reference. ## API Reference Rocket generates standardized endpoints for every configured model. +### Model Endpoints + | Method | Endpoint | Description | | :--- | :--- | :--- | | `POST` | `/:model` | Creates a new record. | | `GET` | `/:model` | Retrieves records with pagination and filtering support. | +| `GET` | `/:model/:id` | Retrieves a specific record by primary key. | | `PATCH` | `/:model/:id` | Performs partial updates on a specific record. | | `DELETE` | `/:model/:id` | Deletes a specific record. | | `POST` | `/:model/search` | Executes advanced search queries. | -| `POST` | `/:model/aggregate` | Performs data aggregations (e.g., count). | +| `POST` | `/:model/aggregate` | Performs data aggregations (count, sum, avg, etc.). | + +### Authentication Endpoints (when `up-auth` is enabled) + +| Method | Endpoint | Description | +| :--- | :--- | :--- | +| `POST` | `/auth/register` | Register a new user account. | +| `POST` | `/auth/login` | Authenticate and receive JWT token. | +| `POST` | `/auth/change-password` | Change password for authenticated user. | +| `POST` | `/auth/forgot-password` | Initiate password reset flow. | +| `POST` | `/auth/otp/verify/login` | Verify OTP for login (when MFA enabled). | +| `POST` | `/auth/otp/verify/register` | Verify OTP for registration. | +| `POST` | `/auth/otp/verify/forgot-password` | Verify OTP for password reset. | ## Development and Testing @@ -116,6 +213,7 @@ npm run lint:check - **Framework**: Fastify - **Architecture**: TypeScript - **Database**: PostgreSQL and SQLite +- **Cache**: Redis - **Validation**: AJV - **Documentation**: Swagger / OpenAPI - **Testing**: Vitest