20.7.6 • Published 8 months ago

the-api v20.7.6

Weekly downloads
2
License
MIT
Repository
github
Last release
8 months ago

NPM version NPM downloads MIT License Build Status: Linux Build Status: Windows Coverage Status Requirements Status Bundle Size Issues Stars Node version Contributors

the-api

The API

Create API asap. Includes the following:

  • log all actions to console with time, unique id, request path and time elapsed since the beginning of the request.

  • error handler with app name, version, error codeName, stack, error name and description for developers.

  • info endpoint: server currentTime, app name, version, uptime, requests count, endpoints

  • login route - register, login, make and refresh app token

  • check token, return unauthorized if token is invalid

  • handle white/black lists, count of requests

  • cache data in memory/redis

  • notes route - example of category/notes api

Install

npm i -S the-api

or

yarn add the-api

Usage

index.js

const TheAPI = require('the-api');
const api = new TheAPI();

const { logs, errors, info, token, access } = api.extensions;
const { login, check, notes } = api.routes;

info.endpointsToShow(login, check, notes);

api.up([
          // select any extension you want to use
  logs,   // log all actions to console with time, unique id, request path and time elapsed since the beginning of the request
  errors, // error handler with app name, version, error codeName, stack, error name and description for developers
  info,   // GET /info endpoint: server currentTime, app name, version, uptime, requests count, endpoints
  login,  // login route - register, login, make and refresh app token
  check,  // check route - small example, just send {ok: 1}
  token,  // check token, return unauthorized if token is invalid
  access, // handle white/black list, count of requests
  notes,  // notes route - example of category/notes api
]);

Change e-mail templates

...
const { login } = api.routes;
...
login.setTemplates({
  register: {
    subject: 'Complete your registration',
    text: 'Hello, use your code {{code}} to POST /register/check',
    html: 'Hello, use your <b>code {{code}}</b> to POST <b>/register/check</b>',
  },
})
...
api.up([
...

examples

  • Get info
curl -vvv localhost:8877/info
  • Create User
curl -vvv -X POST -d '{"login":"aaa", "password":"bbb"}' --header "Content-Type: application/json" localhost:8877/register
  • Refresh Token
curl -vvv -X POST -d '{"refresh":"36ae43be-ae49-46b9-ba8a-027dbcf64fa0"}' --header "Content-Type: application/json" localhost:8877/login
  • Get new Token
curl -vvv -X POST -d '{"login":"aaa", "password":"bbb"}' --header "Content-Type: application/json" localhost:8877/login

.env

namedescriptionexampledefault value
PORTport to listen88788877
API_PREFIXapi prefix/v1
JWT_SECRETJWT secret phrasenruR3@_123dri!aS
JWT_EXPIRES_INexpressed in seconds or a string describing a time span zeit/ms60, 2d, 10h1h

Database

DB options for knex

namedescriptionexampledefault value
DB_CLIENTclientpostgres, mysql, sqlite3sqlite3
DB_HOSTDB hostdb.server
DB_PORTDB port
DB_USERDB userlogin
DB_PASSWORDDB passwordpassword
DB_NAMEdatabase namethe_api_db
DB_SCHEMAdatabase schema, optionalpublic
DB_FILENAMEsqlite3 DB filename./sqlite.db

DB write instance options for knex

namedescriptionexampledefault value
DB_WRITE_CLIENTclientpostgres, mysql, sqlite3sqlite3
DB_WRITE_HOSTDB hostdb.server
DB_WRITE_PORTDB port
DB_WRITE_USERDB userlogin
DB_WRITE_PASSWORDDB passwordpassword
DB_WRITE_NAMEdatabase namethe_api_db
DB_WRITE_SCHEMAdatabase schema, optionalpublic
DB_WRITE_FILENAMEsqlite3 DB filename./sqlite.db

Login Module

namedescriptionexampledefault value
LOGIN_CHECK_EMAILsend code to check registrationtrue, falsefalse
LOGIN_CHECK_EMAIL_DELAYwaiting for check registration code, minutes3060
LOGIN_UNCONFIRMED_FORBIDDon't send token for unconfirmed e-mailtrue, falsefalse
EMAIL_USERnodemailer email userlogin
EMAIL_PASSWORDemail passwordpassword
EMAIL_HOSTemail serversmtp.server
EMAIL_PORTemail port587
EMAIL_SECUREnodemailer secure optiontrue, false
EMAIL_TLS_REJECTUNAUTHnodemailer rejectUnauthorized optiontrue, false

Sentry DSN

namedescriptionexampledefault value
ERRORS_SENTRY_DSNdsn of Sentryhttps://b94116e6a9e24065bd8353e42e8a885a@o4504812935243920.ingest.sentry.io/4504812938299040

Helpers

CRUD helper

Create Create-Read-Update-Delete endpoint for table.

Usage:

const TheAPI = require('the-api');

const api = new TheAPI();
const colors = api.crud({ table: 'colors' });
api.up([colors]);

Generates the following endpoints with CRUD access to colors table:

  • GET /colors
  • POST /colors
  • PATCH /colors
  • DELETE /colors

KOA Knex helper

Implement REST endpoinds for KOA and Knex. Main features:

  • hidde fields by user category
  • required fields list
  • forbidden fields to add list
  • default where in each select request
  • join tables as json array
  • join tabbles aliases
  • limits in joined tabbles
  • define fileds to show in joined tabbles
  • support orderby of joined tabbles
  • .get return selected fields (GET /ship?_fields=id,name)
  • .get searching (GET /ship?name=Item%20name&category_id=3)
  • .get searching by from/to (GET /ship?_from_date=2001&_to_date=2011)
  • .get where not searching: /ships?_fields=title&title!=main
  • .get ilike searching (GET /ship?name~=%25Item%25)
  • .get searching by array (GET /ship?category_id[]=3&category_id[]=5)
  • .get null searching (GET /ship?category_id[]=null)
  • .get pagination (GET /ship?_page=2&_limit=10)
  • .get offset (GET /ship?_skip=100&_limit=10)
  • .get ASC/DESC multifields sorting (GET /ship?_sort=name,-date)
  • .get random sorting (GET /ship?_sort=random())
  • .get pays attention to deleted field in the table (get deleted=false by dafault)
  • .post/.path/.delete implementation

Usage:

//... KOA and Knex flow...
const koaKnexHelper = require('the-api/koa-knex-helper')({ table: 'colors' });

const apiHelper = new koaKnexHelper({
  table: 'ships',
  join: [
    {
      table: 'images', where: 'ships.id = images.ship_id', fields: ['id', 'name'], orderBy: 'is_main DESC, id ASC', limit: imageShowLimit || 1,
    },
    { table: 'categories', where: 'categories.id = ships.category_id' },
    { table: 'lang', where: 'lang.key = ships.name', alias: 'name_lang' },
    { table: 'users', where: 'users.id = ships.user_id', fields: ['company_country', 'company_id', 'company_name', 'first_name', 'second_name', 'id', 'position', 'product', 'status'] },
  ],
  hiddenFieldsByStatus: {
    default: ['imo', 'user_id', 'title', 'message', 'external_company_name', 'external_id', 'external_url'],
    registered: ['external_company_name', 'external_id', 'external_url'],
    owner: ['external_company_name', 'external_id', 'external_url'],
    admin: [],
    root: [],
  },
  required: {
    category_id: 'CATEGORY_ID_IS_REQUIRED',
  },
  forbiddenFieldsToAdd: ['id', 'user_id', 'timeCreated', 'timeUpdated', 'deleted', 'status', 'has_pdf', 'has_rtf'],
  defaultWhere: { sold: false },
});

app.get('/ships', ctx => {
  ctx.body = await apiHelper.get({ ctx });
});

Changelog

History of commits is here

Created by

Dimitry Ivanov 2@ivanoff.org.ua # curl -A cv ivanoff.org.ua

20.7.6

8 months ago

20.7.5

8 months ago

21.1.5

10 months ago

20.7.2

10 months ago

20.7.1

10 months ago

20.7.4

9 months ago

20.7.3

10 months ago

21.1.1

1 year ago

21.1.3

1 year ago

21.1.2

1 year ago

21.1.4

1 year ago

20.6.13

12 months ago

20.6.11

12 months ago

20.6.12

12 months ago

20.6.10

12 months ago

20.6.9

1 year ago

20.6.8

1 year ago

20.6.7

1 year ago

20.6.6

1 year ago

20.6.5

1 year ago

20.6.4

1 year ago

20.6.3

1 year ago

20.6.2

1 year ago

20.6.1

1 year ago

20.5.2

1 year ago

20.5.1

1 year ago

20.4.6

1 year ago

20.4.4

1 year ago

20.4.3

1 year ago

20.4.1

1 year ago

20.4.2

1 year ago

20.3.2

1 year ago

20.3.1

1 year ago

20.3.3

1 year ago

20.2.1

1 year ago

20.0.5

1 year ago

20.0.4

1 year ago

20.0.6

1 year ago

20.1.1

1 year ago

20.0.3

1 year ago

20.0.2

1 year ago

20.0.1

1 year ago

19.11.3

1 year ago

19.11.2

1 year ago

19.11.1

1 year ago

19.10.3

1 year ago

19.10.2

1 year ago

19.10.1

1 year ago

19.9.2

1 year ago

19.9.1

1 year ago

19.8.3

1 year ago

19.8.2

1 year ago

19.8.1

1 year ago

19.7.7

1 year ago

19.7.6

2 years ago

19.7.5

2 years ago

19.0.1

2 years ago

19.0.3

2 years ago

19.0.2

2 years ago

19.0.4

2 years ago

18.9.3

2 years ago

18.9.2

2 years ago

18.9.1

2 years ago

18.9.9

2 years ago

18.9.8

2 years ago

18.9.7

2 years ago

18.9.6

2 years ago

18.9.5

2 years ago

18.9.4

2 years ago

19.7.2

2 years ago

19.7.1

2 years ago

19.7.3

2 years ago

18.8.9

2 years ago

18.8.8

2 years ago

18.8.7

2 years ago

18.8.6

2 years ago

19.6.1

2 years ago

19.6.2

2 years ago

19.5.8

2 years ago

19.5.7

2 years ago

19.5.2

2 years ago

19.5.1

2 years ago

19.5.4

2 years ago

19.5.3

2 years ago

19.5.6

2 years ago

19.5.5

2 years ago

18.9.10

2 years ago

19.4.1

2 years ago

19.4.3

2 years ago

19.4.5

2 years ago

19.4.4

2 years ago

18.8.10

2 years ago

18.8.11

2 years ago

18.8.12

2 years ago

18.8.13

2 years ago

19.3.1

2 years ago

19.2.1

2 years ago

19.1.2

2 years ago

19.1.1

2 years ago

19.1.3

2 years ago

18.2.2

2 years ago

18.2.1

2 years ago

18.1.3

2 years ago

18.1.2

2 years ago

18.1.1

2 years ago

18.8.4

2 years ago

18.8.2

2 years ago

18.8.1

2 years ago

18.8.5

2 years ago

17.1.1

2 years ago

18.7.2

2 years ago

18.7.1

2 years ago

18.6.1

2 years ago

15.3.2

2 years ago

15.3.1

2 years ago

15.3.4

2 years ago

15.3.3

2 years ago

15.3.5

2 years ago

15.3.7

2 years ago

18.5.5

2 years ago

18.5.4

2 years ago

18.5.3

2 years ago

18.5.2

2 years ago

18.5.1

2 years ago

17.0.3

2 years ago

17.0.2

2 years ago

17.0.4

2 years ago

18.4.4

2 years ago

18.4.2

2 years ago

18.4.1

2 years ago

18.3.3

2 years ago

18.3.2

2 years ago

15.2.1

2 years ago

15.2.2

2 years ago

15.2.3

2 years ago

18.3.1

2 years ago

16.0.1

2 years ago

14.9.4

3 years ago

14.9.3

3 years ago

14.9.2

3 years ago

14.5.1

3 years ago

14.9.1

3 years ago

14.5.2

3 years ago

14.5.3

3 years ago

14.2.4

3 years ago

14.6.1

3 years ago

14.2.5

3 years ago

14.6.2

3 years ago

14.7.2

3 years ago

14.7.3

3 years ago

14.10.5

3 years ago

14.10.4

3 years ago

15.1.1

3 years ago

14.4.12

3 years ago

14.4.13

3 years ago

14.4.10

3 years ago

14.4.11

3 years ago

14.3.1

3 years ago

14.10.3

3 years ago

14.3.2

3 years ago

14.10.2

3 years ago

14.10.1

3 years ago

14.7.1

3 years ago

14.8.1

3 years ago

14.4.5

3 years ago

14.8.2

3 years ago

14.8.3

3 years ago

14.4.7

3 years ago

14.8.4

3 years ago

14.4.8

3 years ago

14.4.9

3 years ago

14.4.1

3 years ago

14.4.3

3 years ago

14.4.4

3 years ago

14.1.1

3 years ago

14.1.2

3 years ago

14.1.3

3 years ago

14.1.4

3 years ago

12.4.1

3 years ago

12.4.2

3 years ago

12.0.1

3 years ago

13.0.1

3 years ago

14.2.1

3 years ago

14.2.2

3 years ago

14.2.3

3 years ago

12.3.1

3 years ago

12.3.3

3 years ago

11.1.7

3 years ago

12.6.1

3 years ago

12.6.2

3 years ago

12.6.4

3 years ago

12.2.1

3 years ago

12.2.2

3 years ago

12.2.3

3 years ago

14.0.1

3 years ago

14.0.2

3 years ago

12.5.2

3 years ago

12.5.3

3 years ago

12.5.4

3 years ago

12.5.5

3 years ago

12.5.1

3 years ago

12.1.1

3 years ago

10.2.3

3 years ago

9.2.8

3 years ago

10.2.4

3 years ago

10.0.6

3 years ago

9.2.7

3 years ago

10.2.5

3 years ago

9.2.6

3 years ago

10.2.6

3 years ago

10.2.7

3 years ago

9.2.4

3 years ago

10.2.8

3 years ago

9.2.3

3 years ago

10.2.9

3 years ago

9.2.2

3 years ago

9.2.1

3 years ago

10.0.1

3 years ago

10.0.2

3 years ago

10.2.1

3 years ago

10.0.3

3 years ago

10.2.2

3 years ago

10.0.4

3 years ago

9.2.9

3 years ago

7.1.1

3 years ago

10.2.10

3 years ago

10.2.11

3 years ago

9.1.1

3 years ago

5.4.1

3 years ago

9.3.5

3 years ago

9.3.4

3 years ago

9.3.3

3 years ago

9.3.2

3 years ago

9.3.1

3 years ago

10.1.1

3 years ago

7.0.1

3 years ago

9.2.10

3 years ago

11.1.5

3 years ago

11.1.6

3 years ago

11.1.3

3 years ago

11.1.1

3 years ago

11.1.2

3 years ago

5.3.3

4 years ago

5.3.2

4 years ago

5.3.1

4 years ago

5.2.8

4 years ago

5.2.7

4 years ago

5.2.6

4 years ago

5.2.4

4 years ago

5.2.3

4 years ago

5.2.5

4 years ago

5.2.2

4 years ago

5.2.1

4 years ago

5.1.2

4 years ago

5.1.1

4 years ago

5.0.1

4 years ago

4.4.1

4 years ago

4.3.2

4 years ago

4.3.1

4 years ago

4.5.2

4 years ago

4.5.1

4 years ago

4.4.2

4 years ago

4.3.3

4 years ago

4.2.1

4 years ago

4.1.1

4 years ago

4.0.1

5 years ago

3.9.5

5 years ago

3.9.4

5 years ago

3.9.3

5 years ago

3.9.1

5 years ago

3.8.1

5 years ago

3.7.5

5 years ago

3.7.4

5 years ago

3.7.3

5 years ago

3.7.1

5 years ago

3.7.2

5 years ago

3.6.2

5 years ago

3.6.1

5 years ago

3.5.2

5 years ago

3.5.1

5 years ago

3.3.1

5 years ago

3.0.2

5 years ago

3.0.1

5 years ago

2.1.1

5 years ago

2.0.4

5 years ago

2.0.2

5 years ago

2.0.1

5 years ago

1.2.3

5 years ago

1.2.1

5 years ago

1.1.3

5 years ago

1.1.1

5 years ago

1.0.1

5 years ago

0.1.2

5 years ago

0.1.1

5 years ago