NLdoc API Specification

An OpenAPI 3.1.0 compatible specification for the NLdoc API. This TypeScript library provides a comprehensive API framework for document conversion services, health monitoring, and file management.

Overview

This specification defines a standardized REST API for NLdoc services including:

• Document conversion operations
• Server-Sent Events (SSE) for conversion progress tracking
• File retrieval and management
• Health check endpoints

The API follows RPC-style principles inspired by REST, using clear, action-driven endpoints and standard HTTP semantics to deliver streamlined operations.

Getting Started

Prerequisites

• Node.js >= 22.0.0 < 23.0.0
• npm >= 10.0.0 < 12.0.0

Installation

Install the package via npm:

npm install @nldoc/api-specification

Or using yarn:

yarn add @nldoc/api-specification

Basic Usage

import {
  specification,
  validExamples,
  invalidExamples
} from '@nldoc/api-specification';

// Access the OpenAPI specification
console.log(specification);

// Use valid examples for testing
console.log(validExamples);

// Use invalid examples for validation testing
console.log(invalidExamples);

Accessing the OpenAPI Specification

After building the project, the complete OpenAPI 3.1.0 specification is available at:

# Build the project first
npm run build

# The OpenAPI specification is now available at:
# - public/openapi.json (JSON format)
# - public/index.html (Interactive HTML documentation)

Development

Local Setup

1. Clone the repository:

   git clone https://gitlab.com/logius/nldoc/spec/api.git
   cd api-specification

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Available Scripts

• npm run test - Run the test suite with Vitest and generate coverage reports
• npm run build - Build the OpenAPI specification, examples, and TypeScript files
• npm run lint - Lint the codebase using ESLint
• npm run format - Format code using Prettier
• npm run format:check - Check code formatting
• npm run fix - Auto-fix linting and formatting issues
• npm run lint:openapi - Validate OpenAPI specification against ADR standards and generate reports
• npm run lint:spectral - Validate against Dutch API Design Rules (ADR 2.1)
• npm run lint:vacuum - Generate an HTML report for the OpenAPI specification

Building Components

The build process consists of several steps:

1. OpenAPI Generation: npm run build:openapi - Generates the OpenAPI JSON specification
2. Example Extraction: npm run build:examples - Extracts valid and invalid test examples
3. TypeScript Compilation: Compiles TypeScript to JavaScript for distribution
4. Documentation: npm run build:redocly - Generates HTML documentation using Redocly

API Endpoints

The specification defines the following main endpoints:

Core Operations

• POST /conversion: Convert files to different formats
• GET /conversion/{uuid}: Stream conversion events via Server-Sent Events (SSE)
• GET /file/{key}: Retrieve converted files
• HEAD /file/{key}: Check file metadata

Health Monitoring

• GET /health: Get health status with detailed response
• HEAD /health: Quick health check

Headers and Parameters

The API uses standard headers for request tracking and versioning:

• X-Trace-Id: Distributed tracing identifier
• X-Request-Id: Unique request identifier
• API-Version: API version information
• Content-Type: Content type for requests and responses

API Documentation

The generated OpenAPI specification can be viewed:

1. Locally: After building, open public/index.html in your browser
2. Online: View the latest release documentation

Testing

Run the test suite:

npm test

Contributing

We welcome contributions! Please ensure:

1. All tests pass (npm test)
2. Code is properly formatted (npm run format:check)
3. Linting rules are followed (npm run lint)
4. OpenAPI specification is valid (npm run lint:openapi)
5. Compliance with Dutch API Design Rules (npm run lint:spectral)

License

This project is licensed under the European Union Public License 1.2 - see LICENSE for details.

Acknowledgements

• Built on OpenAPI 3.1.0 specification
• Follows Dutch API Design Rules (ADR) version 2.1
• Uses Redocly for API documentation generation
• Validated with @quobix/vacuum and Spectral