Overview

Contract to Service Runtime with MongoDB interaction

Apistry provides a generic runtime engine that turns OpenAPI 3.0 contracts into fully functional REST APIs without writing service-specific code. It includes built-in MongoDB integration for automatic CRUD operations, advanced querying, and request/response validation based on contract schemas.

[] (https://www.npmjs.com/package/apistry)

• OpenAPI Contract: Define your API using OpenAPI 3.0 specifications, and the service automatically creates functional endpoints
• Swagger UI Documentation: Automatically generated interactive API documentation available at /docs
• Auto-Collection Creation: Automatically validates and creates MongoDB database and collections based on OpenAPI tags during server startup
• MongoDB Integration: Built-in CRUD operations with advanced query capabilities
• Flexible Querying: Support for operators like eq, neq, gt, lt, gte, lte, isNull, and wildcard matching
• Bulk Operations: Support for bulk inserts, updates, and deletes
• Response List Handling: Optional metadata in responses including total count and pagination information
• Validation: Automatic parameter, request/response validation using AJV and JSON Schema
• Fastify-Based: Built on the high-performance Fastify web framework

Overview

• 🧰 Installation
• 💻 Usage
• 📖 Documentation

🧰 Installation

• The easiest way to install Apistry is to use either npm or yarn:

npm install -g apistry

Or yarn:

yarn global add apistry

💻 Usage

1. OpenApi contract

Apistry, being a contract based service, needs a well-defined contract to startup. The following examples have been provided to get you started quickly:

• Books (books.v1.yaml)
• Cars (cars.v1.yaml) - Has most sample endpoints and features
• Utils (utils.v1.yaml) - Simple utility endpoints for health checks and ???
• Videos (videos.v1.yaml)
• Pets (pets.v1.yaml)
• Notes (notes.v1.yaml) - A Polymorphic example

Download one or all of these to get started quickly or create your own.

2. MongoDB Setup

Apistry requires a MongoDB database for document storage and operations. Both local and cloud-hosted MongoDB instances are supported.

Database Compatibility: While Apistry is designed to work with any JSON document database that supports standard querying capabilities, the current release provides native integration exclusively with MongoDB.

Connection Configuration: For security best practices, the MongoDB connection string must be provided as an environment variable. Apistry supports .env files for local development environments.

Note: Be sure to provide the database name in your connection string. When started, database and collection will be created if they do not already exist.

Hosted MongoDB Example:

export DB_CONNECTION="mongodb+srv://myserver:****@myserver-db.ojsguxa.mongodb.net/mydb?appName=myserver-db"

Local MongoDB Example:

export DB_CONNECTION="mongodb://localhost:27017/mydb"

Or create an .env file:

DB_CONNECTION=mongodb+srv://myserver:****@myserver-db.ojsguxa.mongodb.net/mydb?appName=myserver-db

2. Confirm Database Connection

Before starting the server, it's a good idea to test the database connection to your DB_CONNECTION is correct.

All paths are relative to the current working directory.

apistry testConnection

or

apistry testConnection -e path/to/.env

Output:

apistry serve --env .. --contract ../contracts/dist

Loading 6 contract(s): [
  'books.v1.yaml',
  'cars.v1.yaml',
  'notes.yaml',
  'pets.v1.yaml',
  'utils.v1.yaml',
  'videos.v1.yaml'
]
MongoDB connected → apistry
✅ All required collections exist
ContentTypeParser for 'application/xml' not found
ContentTypeParser for 'application/x-www-form-urlencoded' not found
ContentTypeParser for 'application/octet-stream' not found
📚 Swagger UI available at /docs
Loaded 41 routes successfully
Server listening at http://[::1]:3000
Server listening at http://127.0.0.1:3000
🚀 Server running on http://localhost:3000
📖 API Documentation: http://localhost:3000/docs

Additional options are available:

apistry --help

Output:

Usage: apistry [options] [command]

Apistry CLI

Options:
  -v, --version              Output the version number
  -h, --help                 display help for command

Commands:
  serve [options]            Start the API development server
  testConnection [options]   Test the MongoDB database connection
  clearCollection [options]  Clear all documents from a MongoDB collection
  import [options]           Import JSON or CSV files into collections
  export [options]           Export collection(s) to JSON or CSV files
  help [command]             display help for command

3. Start the Server

Starting the server is very fast and easy. All files and paths are relative to the current working directory.

Just provide the path to your OpenAPI contract file:

apistry serve -c contracts/cars.v1.yaml

If using an environment file, provide the path to the directory containing the .env file:

apistry serve -e contracts/.env -c contracts/cars.v1.yaml

Output:

✅ All required collections exist in database
🚀 Server running on http://localhost:3000

📖 Documentation

• Documentation
  • Getting Started - The basics of Apistry.

Once you've had a look through the getting started material, some of these guides can help you become a power user.

• Using the command-line interface - Quickest way to get going with Apistry is in the CLI.

ℹ️ Support

If you need help using Apistry or have any questions, you can use GitHub Discussions

If you have a bug or feature request, create an issue for it.

📜 License

Apistry is 100% free and open-source, under Apache License 2.0.