xhelpers-api

xHelpers API

Description

xhelpers-api is an open-source project that aims to simplify the implementation of RESTful APIs. It provides a set of helper functions and plugins to help developers build efficient, secure, and scalable APIs. This documentation will guide you through the different sections and configurations of the project..

• The project is a collection of libraries and tools that can be used to create and deploy micro-services. It has a comprehensive suite of features such as ORM/ODM (Sequelize, Mongoose), API SSL, API SSO (Github, Facebook, Google), API security (JWT, AppKey), API logging (AWS, Sentry), API documentation (Swagger), API queue operator (AMQP, RabbitMQ).

• The project has a CLI tool with usefull functions, check it out: xhelpers-cli.

• The project is actively maintained and updated to provide the best experience for developers. It is an open source project and anyone can contribute to it and help make it even better.

Stack

• TypeScript 4.9.5.
• Node.js 18.14.1.
• Hapi 21.3.0.
• Mongoose 6.10.0.
• Sequelize 6.29.0.

Roadmap

• Improve documentation
• Add more samples

Getting Started

To start using xhelpers-api in your project, you need to install it as a dependency:

$ npm i xhelpers-api

Configuration

xhelpers-api allows you to configure different aspects of your API, such as logging, database connections, and security settings. To configure these settings, you can use the options on the method createServer.

Example: Microservice API using xhelpers-api in a single file

Here's an minified example of a microservice API using xhelpers-api:

import { createServer } from "xhelpers-api/lib/server";
import { BaseRouteSimple } from "xhelpers-api/lib/route";
import { Boom, uuid, Joi, dotenv } from "xhelpers-api/lib/tools";

dotenv.config();

class RequestService {
	async createJob(u: any, server: any): Promise<string | Boom.Boom> {
		return uuid.v4();
	}
}

class Routes extends BaseRouteSimple {
	constructor(private service = new RequestService()) {
		super(["api", "Jobs"]);
		this.route("POST", "/api/jobs", {}, false)
			.validate({
				payload: Joi.object({
					id: Joi.string().required().description("id"),
				}),
			})
			.handler(async (r, h, u) => {
				const result = await this.service.createJob(u, r.server);
				return Boom.isBoom(result) ? result : h.response(result).code(200);
			})
			.build();
	}
}

export const start = async () => {
	// create hapijs server with xhelpers options
	const server = await createServer({
		serverOptions: {},
		options: {
			swaggerOptions: {
				info: {
					title: "Minified demo",
					version: "1.0",
				},
			},
			routeOptions: { routes: "" },
		},
	});
	// register local routes
	server.route(new Routes().buildRoutes());
	// start server
	server.start();
	return server;
};

start();

Key Components

createServer

The createServer function from the xhelpers-api/lib/server module is used to create a HapiJS server with the provided xhelpers-api options.

import { createServer } from "xhelpers-api/lib/server";

BaseRouteSimple

The BaseRoute/BaseRouteSimple class from the xhelpers-api/lib/route module is used to define routes and their handlers. It provides a simple and organized way to manage routes.

import { BaseRouteSimple } from "xhelpers-api/lib/route";

Tools

The xhelpers-api/lib/tools module provides a set of utilities and tools that simplify common tasks, such as generating UUIDs, validating payloads using Joi, and handling errors with Boom.

import { Boom, uuid, Joi, dotenv } from "xhelpers-api/lib/tools";

Defining Services

You can define services by creating a class and implementing the required methods. In the example above, a RequestService class is defined with a createJob method.

class RequestService {
  async createJob(u: any, server: any): Promise<string | Boom.Boom> {
    return uuid.v4();
  }
}

Defining Routes

Routes can be defined by extending the BaseRoute/BaseRouteSimple class and implementing the required routes. In the example above, a Routes class is defined with a single route for creating a job.

class Routes extends BaseRouteSimple {
	constructor(private service = new RequestService()) {
		super(["api", "Jobs"]);
		this.route("POST", "/api/jobs", {}, false)
			.validate({
				payload: Joi.object({
					id: Joi.string().required().description("id"),
				}),
			})
			.handler(async (r, h, u) => {
				const result = await this.service.createJob(u, r.server);
				return Boom.isBoom(result) ? result : h.response(result).code(200);
			})
			.build();
	}
}

Starting the Server

The server is started by calling the start function, which initializes the server with the provided options, registers the routes, and starts the server.

const server = await createServer({
  serverOptions: {},
  options: { routeOptions: { routes: "" } },
});
server.start();

Output of running server:

Starting Xhelpers Hapi server API
Settings API: Mongoose disabled;
Settings API: Sequelize disabled;
Settings API: SSL disabled;
Settings API: SSO disabled;
Settings API: JWT disabled;
Settings API: AppKey disabled;
Settings API: CronJobs disabled;
Settings API: Sentry disabled;
====================================================================================================
🆙  Server doc    : http://localhost:5000/documentation
🆙  Server api    : http://localhost:5000/
====================================================================================================
Routing table:
        🔎  get -       /documentation
        🔎  get -       /swagger.json
        🔎  get -       /health
        🔎  get -       /liveness
        📄  post -      /api/jobs
====================================================================================================

Default Routes

🆙  Server doc    : http://127.0.0.1:5000/documentation
🆙  Server health : http://127.0.0.1:5000/health
🆙  Server health : http://127.0.0.1:5000/liveness

Examples

You can find example code in the examples directory of the xhelpers-api GitHub repository. These examples demonstrate how to use the different features and configurations of xhelpers-api in a real-world scenario.

Feel free to explore these examples and use them as a reference when building your own APIs with xhelpers-api.

Building/Contributing

Contributions to xhelpers-api are welcome! Please refer to the CONTRIBUTING.md file for detailed guidelines on submitting pull requests, reporting issues, and more.

If you have any questions or need assistance, feel free to open an issue on the xhelpers-api GitHub repository.

# build tsc
$ npm run build

Test

$ npm run test

Test Coverage

$ npm run test:coverage
$ npm run cover:report