BreezeAPI

Getting Started with BreezeAPI

Welcome to BreezeAPI! This guide will help you install BreezeAPI and create your first project. BreezeAPI is a TypeScript framework for Bun that makes building APIs a breeze with file-based routing and plug-and-play WebSocket integrations.

Prerequisites

Before you begin, make sure you have the following installed:

  • Bun (version 1.0.0 or higher)
  • Node.js (version 18.0.0 or higher)

Installation

You can install BreezeAPI using Bun:

Terminal
bun add @breezeapi/core

Creating a New Project

Currently, BreezeAPI does not have a CLI tool for project scaffolding. However, you can create a new project manually by creating a directory and initializing it with Bun. In your server/index file you can import the BreezeAPI and create a new instance of it.

import { BreezeAPI, Config, } from '@breezeapi/core';
import {cors} from '@breezeapi/cors';

/**
 * Creates a new RCS API instance using BreezeAPI.
 * 
 * This API serves as the data interface for RCS. It
 * includes both REST routes and socket connections.
 * 
 * @type {BreezeAPI} The BreezeAPI instance configured for RCS
 * @property {string} title - The title of the API shown in documentation
 * @property {string} description - Brief description of the API's purpose
 * @property {string} version - Current API version (semantic versioning)
 * @property {string} apiDir - Directory path for REST API route definitions
 * @property {string} socketDir - Directory path for WebSocket handlers
 * @property {boolean} debug - Flag to enable debug mode for additional logging
 */
const MYAPI = new BreezeAPI({
    title: 'MY API',
    description: 'Testing API for the Documentation',
    version: '1.0.0',
    apiDir: 'routes',
    socketDir: 'socket',
    debug: true, // Enable debug mode for additional logging
   /*  SSE does not work with cors yet
   sseCors: {
        origin: '*',
        methods: 'GET',
        headers: 'Content-Type',
        credentials: false
    }*/
});

MYAPI.use(cors());  // Example middleware usage

// Start the server
MYAPI.serve(4000, () => {
    const hostname = process.env.HOST || 'localhost';
    console.log(`✨ Server is running on: http://${hostname}:4000`);
    console.log(`✨ API Docs: http://${hostname}:4000/docs`);
    console.log(`✨ openapi Data: http://${hostname}:4000/openapi.json`);
});

Project Structure

After creating a new project, you'll have a directory structure that looks like this:

my-api/
├── routes/
│   ├── route.ts // this would than be the route for /
│   └── users/
│       ├── route.ts // this would be the route for /users
│       └── [id]/
│           └── route.ts // this would be the route for /users/:id
├── middleware/
│   └── logger.ts // example middleware (not required)
├── sockets/
│   ├── socket.ts // this would than be the socket for /socket
│   └── chat/
│       ├── socket.ts // this would be the route for /socket/chat
│       └── [id]/
│           └── socket.ts // this would be the socket for /chat/:id
├── config.ts
├── tsconfig.json
└── package.json

Starting the Development Server

To start the development server, navigate to your project directory and run:

Terminal
cd my-api
bun run dev

This will start the development server at http://localhost:4000 or your custom configured port. For hot reloading add a --watch behind your command.

Your First API Endpoint

Let's create a simple API endpoint. BreezeAPI uses a file-based routing system similar to Next.js. Each file in the routes directory corresponds to an API endpoint.

Here's an example of a simple endpoint in routes/hello.ts:

import { BreezeRequest, BreezeResponse } from "breeze-api";

export async function GET(req: BreezeRequest) {
  return BreezeResponse.json({
    message: "Hello, World!"
  });
}

With this file in place, you can now access http://localhost:3000/hello and you'll receive a JSON response with the message "Hello, World!".

Next Steps

Now that you have BreezeAPI installed and running, you can:

Documentation HomeProject Structure