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.
- Improve documentation
- Add more samples
To start using xhelpers-api in your project, you need to install it as a dependency:
$ npm i xhelpers-apixhelpers-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.
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();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";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";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";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();
}
}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();
}
}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();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
====================================================================================================
🆙 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
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.
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$ npm run test$ npm run test:coverage
$ npm run cover:report