adon-api
Advanced tools
Comparing version 2.2.2 to 2.2.3
{ | ||
"name": "adon-api", | ||
"version": "2.2.2", | ||
"version": "2.2.3", | ||
"description": "API for all Adon-based projects", | ||
@@ -5,0 +5,0 @@ "main": "dist/src/index.js", |
# adon-api | ||
Express JS + Typescript + Jest development made easier. The goal is for us to easily build websites or APIs without managing the same dependencies and breaking out of our standards and conventions each time. We follow convention and configuration over code so that all future projects are handled easily. | ||
## Project stats | ||
* Package: [![npm](https://img.shields.io/npm/v/adon-api.svg)](https://www.npmjs.com/package/adon-api) [![npm](https://img.shields.io/npm/dm/adon-api.svg)](https://www.npmjs.com/package/adon-api) | ||
* License: [![GitHub](https://img.shields.io/github/license/adonisv79/adon-api.svg)](https://github.com/adonisv79/adon-api/blob/master/LICENSE) | ||
* CICD: [![Codacy Badge](https://app.codacy.com/project/badge/Grade/8308805088ac436b82f87e48a48633a1)](https://www.codacy.com/gh/adonisv79/adon-api/dashboard?utm_source=github.com&utm_medium=referral&utm_content=adonisv79/adon-api&utm_campaign=Badge_Grade) [![Known Vulnerabilities](https://snyk.io/test/github/adonisv79/adon-api/badge.svg)](https://snyk.io/test/github/adonisv79/adon-api) | ||
* develop: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/adonisv79/adon-api/tree/develop.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/adonisv79/adon-api/tree/develop) | ||
* master: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/adonisv79/adon-api/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/adonisv79/adon-api/tree/master) | ||
* CICD: [![Codacy Badge](https://app.codacy.com/project/badge/Grade/8308805088ac436b82f87e48a48633a1)](https://www.codacy.com/gh/adonisv79/adon-api/dashboard?utm_source=github.com&utm_medium=referral&utm_content=adonisv79/adon-api&utm_campaign=Badge_Grade) [![CircleCI](https://dl.circleci.com/status-badge/img/gh/adonisv79/adon-api/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/adonisv79/adon-api/tree/master) | ||
## Running the sample | ||
On the root of this project is a simplified sample project. Run it with the following command... | ||
```npm | ||
npm run start:sample | ||
``` | ||
Then from your browser, check the route endpoints for these | ||
* http://localhost:3000 | ||
@@ -21,3 +25,5 @@ * http://localhost:3000/test | ||
## How it works? | ||
Technologies used: | ||
* Express JS - our core framework is based on express and so this module will provide a library to easily kickstart an express js web service. | ||
@@ -31,2 +37,3 @@ * TypeScript - Our projects will be based only on TypeScript so make sure this is installed on your system. | ||
### logger | ||
The built-in logger (winston) is set to utilize the common 6 logging levels in my dev experience. You can access the logger instance as part of the ExpressApp instance's 'log' property. | ||
@@ -39,2 +46,3 @@ | ||
``` | ||
const levels = { | ||
@@ -50,2 +58,3 @@ crit: 0, // Critical errors that impact the stability of the system rendering it useless or break | ||
### RouteManager | ||
The RouteManager structures how REST routes are defined on the project. It also adds generic logs and a 'trace-token' to the request header that we can use to better debug logs for a particular request (user must make sure to add this explicitely to the meta of the logs). To define your routes, create a {*.rt.ts} file in the project's "routes" folder. It should export as default a function named route that accepts 2 parameters (the ExpressApp instance and the express router object). | ||
@@ -69,5 +78,8 @@ | ||
``` | ||
## Installation | ||
install the following | ||
* adon-api framework (this) | ||
* adon-api framework (this) | ||
```npm | ||
@@ -78,4 +90,6 @@ npm i adon-api --save | ||
## Redis Dependency | ||
As mentioned above, this API depends on Redis particularly for the RateLimitter. I would recommend the use of redis for session management and other caching concerns as well. You can run it wherever and however you want. If you have docker for example (which I use for my developments) then just run the following to spin a new redis instance | ||
``` | ||
``` sh | ||
docker run --name local-redis -p 6379:6379 -d redis | ||
@@ -85,4 +99,6 @@ ``` | ||
## How to use | ||
Create index.ts in your project root and enter the following | ||
```typescript | ||
``` typescript | ||
import { ExpressApp, ExpressAppConfig, EnvConfig } from 'adon-api' | ||
@@ -120,2 +136,3 @@ | ||
### Environment configurations | ||
* PORT - sets the port number where the service will listed to. (Default: 3000) | ||
@@ -125,2 +142,3 @@ * SERVER_CORS_ALLOWED_ORIGINS - sets the allowed request origins urls. multiple URLs are divided by semicolon. (Default: '*') | ||
Either set in your machine environment the values or create a file named '.env' in the root of the application then enter the following | ||
```text | ||
@@ -132,2 +150,3 @@ PORT=3000 | ||
You can add more configurations here as much as you like and they can be accessed in code as | ||
```javascript 1.6 | ||
@@ -142,2 +161,3 @@ import { EnvConfig } from 'adon-api' | ||
## Routes | ||
Adding new routes is simple and organized in this framework. First create a 'routes' folder in the root. | ||
@@ -148,2 +168,3 @@ Add new file inside the routes folder with the 'rt.ts' extension. To create a root route '/' name the file 'index.rt.ts' | ||
For this sample, lets create a file named 'index.rt.ts' and 'users_test.rt.ts' then enter the following in both files | ||
```typescript | ||
@@ -163,2 +184,2 @@ import { Router, Request, Response } from 'express' | ||
Run the application and use postman to invoke GET on 'http://localhost:3000/', 'http://localhost:3000/test' and 'http://localhost:3000/users/properties/ | ||
Run the application and use postman to invoke GET on 'http://localhost:3000/', 'http://localhost:3000/test' and '<http://localhost:3000/users/properties/> |
173
40470