@vvlad1973/base-api

Base API class with OpenAPI schema validation.

Features

• OpenAPI 3.0+ specification support
• Automatic parameter validation using JSON Schema
• Event emitter support for API events
• TypeScript support with full type definitions

Installation

npm install @vvlad1973/base-api

Usage

Basic API Client

import { BaseApi, type BaseApiOptions } from '@vvlad1973/base-api';

class MyApi extends BaseApi {
  protected async callApi<T>(
    methodName: string,
    params: object,
    routeId?: string,
    contentType?: string
  ): Promise<T> {
    // Implement your API call logic here
    const response = await fetch(`/api/${methodName}`, {
      method: 'POST',
      headers: { 'Content-Type': contentType || 'application/json' },
      body: JSON.stringify(params)
    });
    return response.json();
  }
}

// Initialize with OpenAPI specification
const options: BaseApiOptions = {
  specification: {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
    components: {
      schemas: {},
      responses: {}
    },
    paths: {}
  }
};

await MyApi.initializeWithSpec(options);

// Create instance and use
const api = new MyApi();

With Async Specification Loading

const options: BaseApiOptions = {
  specification: async () => {
    const response = await fetch('/api/openapi.json');
    return response.json();
  }
};

await MyApi.initializeWithSpec(options);

API Reference

BaseApi

Abstract class that provides OpenAPI validation functionality.

Static Methods

• initializeWithSpec(options: BaseApiOptions): Promise<void> - Initialize the validator with OpenAPI specification
• init(options: BaseApiOptions): Promise<void> - Internal initialization method

Protected Methods

• callApi<T>(methodName: string, params: object, routeId?: string, contentType?: string): Promise<T> - Abstract method to implement API calls
• executeCallApi<T>(methodName: string, params: object, routeId?: string, contentType?: string): Promise<T> - Execute API call with validation

Types

interface BaseApiOptions {
  specification: OpenApiSpecification | (() => Promise<OpenApiSpecification>);
}

interface OpenApiSpecification {
  openapi: string;
  info: { title: string; version: string };
  components: {
    schemas: Record<string, unknown>;
    responses: Record<string, unknown>;
  };
  paths: Record<string, unknown>;
}

Constants

• DEFAULT_CONTENT_TYPE - Default content type for API calls ('application/json')
• JSON_SCHEMA_URL - JSON Schema specification URL
• ContentTypeSuffix - Enum with content type suffixes

Utility Functions

• capitalize(str: string): string - Capitalize first letter
• getMethodOptionsName(methodName: string, suffix: string): string - Get method options schema name
• resolveRefName(ref: string): string - Resolve JSON Schema $ref name
• getMethodName(path: string, method: string): string - Generate method name from path and HTTP method
• collectSchemas(schema: object, schemasMap: Map): Map - Collect all referenced schemas
• generateParamsSchemas(path: string, request: object, schemasMap: Map): void - Generate parameter schemas

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

Dependencies

• @vvlad1973/data-validator - JSON Schema validation

License

MIT License with Commercial Use restrictions. See LICENSE file for details.

Author

Vladislav Vnukovskiy [email protected]

Repository

https://github.com/vvlad1973/base-api