README
NodeJS Module Rest-API
api-bxcore - это минималистичный и гибкий фреймворк предоставляющий обширный набор функций для построения REST-API на Node.js.
Имеет в своем распоряжении множество служебных методов и промежуточных обработчиков, для создания надежного професионального сервера быстро и легко.
Данный модуль предоставлет веб панель для просмотра, тестирование и анализа методов API.
Install module
npm i api-bxcore
Quick start
const express = require('express');
const app = express();
const RestAPI = require('api-bxcore');
const restapi = new RestAPI({}, {
auth_user: (user) => {
return new Promise(resolve => {
if (user.session.auth && user.session.user_id)
resolve({status: true, user_id: user.session.user_id});
else
resolve({status: false})
});
},
auth_admin: (user) => {
return new Promise(resolve => {
if (user.session.auth && user.session.user_id&& user.session.admin ===1)
resolve({status: true, user_id: user.session.user_id});
else
resolve({status: false})
});
}
});
app.use('/api/v1', restapi.expressRouter);
- нужно описать основные принципы работы
- описать что такое функции auth_user auth_admin
- описать как создается конфигурационый файл
- описать что такое api express router
- описать файл конфигураций что значит каждый из параметров в нем
Контрольная сумма парамметров запроса для restAPI авторизации
let param = {...__GET, ...__POST};
const checksumParams = crypto.createHash('sha256')
.update(JSON.stringify(param))
.digest('hex');
API Types and validate
String:
/**
* @param {string} options.regexp - STRING REGEXP (optional)
*/
API.types.STRING(lenght,options)
Number:
/**
* ┌──────────────── fixed (3)
* 13.556 ───────── length (5)
* @param {string} options.regexp - STRING REGEXP (optional)
*/
API.types.FLOAT(length,fixed,options) //float number
API.types.INTEGER(length,options) // integer
Date:
/**
* @param {number} options.zone_utc - Convert to ZONE (example 0 = UTC) (optional)
*/
API.types.DATE(options)
Enum:
API.types.ENUM(...values)
// example API.types.ENUM('active','pending','deleted')
Boolean:
API.types.BOOLEAN()
Object:
API.types.OBJECT()
Array:
API.types.ARRAY()
FILE: (validator soon)
API.types.FILE()
Own type
You can also create your own type.
for this you need to add the file to the PROJECT_ROOT/api_plugins folder
Example
// PROJECT_ROOT/api_plugins/object-id-type.js
const mongoose = require('mongoose');
module.exports = (API) => {
class _ObjectId {
constructor(len, options) {
this.name = 'ObjectID';
}
valid(v) {
if (!v || v === '' || typeof v !== 'string' || !mongoose.Types.ObjectId.isValid(v))
return {
success: false,
error: 'Value is not ObjectId'
};
return {success: true, value: v};
}
}
API.types.ObjectId = () => {
return new _ObjectId();
};
};
//Example use type
API.types.ObjectId()
API File example
./api/GROUP_PATH/API_file.js
module.exports = (API, redis) => {
// method api/v1/GROUP_PATH/API_file/test
API.register('test', async (user, param) => {
return {ok:1};
}, {
title: 'Test API',
level: 0,// 0 public,1 user,2 admin,3 server
description: 'This method for test and learn api. =)',
group: "Testing API",
param: {
test:{
type: API.types.STRING(10),
error_code:12345678,
title: 'example param',
required: true
}
},
response: [{
name: 'data.example',
type: "string",
title: 'example res',
default: '1'
}]
});
};
Каждый register должен содержать function c return Promise важно чтоб каждый метод в результате выполненея возвращял промис Как генерируется имя метода? api/v1/ + путь к файлу с методом + (1 параметр из register если он является строкой) таким образом мы получаем api/v1/папка1/папка2/файл/test
Обработка ошибок
Ошибки имеют строгую структуру все ответы апи возвращяют ответ в виде JSON:
Пример error response:
{
"success": false,
"error": {
"apiError": true,
"message": "Page not found",
"errorType": "api",
"object": {
},
"level": 0,
"errorCode": 4041543664702404,
"stack": "Object.API.register [as fn] (./path/api/file.js:444:52)"
},
"latency_ms": 4,
"requestId": "1543748408108-wirUSou"
}
Часто нам необходимо описовать свои ошибки в методах для того чтоб наш клиент понимал что пошло не так в API встроена удобная и гибкая система содание ошибок:
Генерирование ошибок в методах:
Вам достаточно будет использовать данный код в своем методе: (метод сразу вернет Promise.reject)
return API.error.response("Error message example",55511111)
данный способ подойтет в большенстве случаев он принимает 3 параметра (message,errorcode,params) параметры не обезательный но если ваш метод должен вернуть чтото дополнительно вы можете его использовать.
Более гибкий способ описание ошибок:
return Promise.reject(
API.error.create("Error message example",'api',{},10,55511111,500)
)
Данный метод принимает параметры тип и уровенть ошибки , а также statusCode с которым будет возращен запрос параметры данного метода (message, type, params, level, errorCode, statusCode) Будте внимательны так как данный метод не возвращяет в себе reject он создает только нужный обект для его возврата API вам необходимо вернуть ответ его в Promise.reject()
Каждый метод имеет документацию в которой
title - заголовок метода
level - уровень доступа к методу
0 - публичный метод авторизация не требуется 1 - пользовательский метод перед вызовом будет вызвана функция auth_user которая должна вернуть status: true если юзер авторизован а также может вернуть дополнитлеьно user_id для того чтоб в методе был параметр auth.user.user_id 2 - Админский метод аналогично как и юзерский функция проверок auth_admin 3 - Серверный метод может быть вызван только на севрере (к примеру в других методах) API.call($method,$user,$params,'server')description - описание метода (подробности предупреждениея и другая информация по методу)
group - группа метода (категория к кому относится метод для документации чтоб удобно оформить документацию)
hide - не показывать данный метод в списке (документации) (секретный метод) (optional)
param - параметры
paramName: { type: API.types.STRING(10), // тип параметра error_code:12345678, // код ошибки в если параметр прийдет не валидный title: 'example param', // описание required: true // обезательный } // параметры также может быть массивом paramArray: [{ type: API.types.STRING(10), // тип параметра error_code:12345678, // код ошибки в если параметр прийдет не валидный title: 'example param', // описание required: true // обезательный }] // в данном случаи будет проверен каждый елемент массива на сотвествие типа и если стоит required то массив должен иметь хотябы один елемент // параметр также может быть массивом с обектами данном случаи будет проверено весь массив с нужными обектами paramArray: [{param1:{type...},param2:{type...}}response - массив в котором описуется что вернет метод
на основе этой документации все параметры будут валидироватся и уровни доступы до того как будет вызван сам параметр если в методе произойдет синтаксическая ошибка метод вернет код 500 с указанием ошибки
After starting the application, the ./api/ and ./config/ folder will be created.
- ./api/ - directory with API
- ./config/api_config.json - configuration file
конфиграционый файл создается при первом запуске правильная конфигурация влият на работу апи все параметры имееют логиченые название вы можете ознакомится с ним самостоятельно
Plugins (./api_plugins)
DDOS/Flood protect
https://gist.github.com/b-m-9/f84b80499f0b99ff41a13a6766bbb2ac
How to use:
const ddosKey = 'protect-1'; // key for count req const floodSign = await API.plugin.ddos.lockApi(auth.ddosKey, blockForSec); await API.plugin.ddos.checkLockApi(auth.ddosKey, floodSign, delayMS);
Param types ObjectId
https://gist.github.com/b-m-9/04fcacb8548d4ac2d010c80d25e9a7ac
How to use:
param:{ newsId: { type: API.types.ObjectId(), // ... } }
Quick param pagination API.method
https://gist.github.com/b-m-9/8aa319d8e522968fda191082599898a2
// in source validator let page = API.plugin.pageAPI.get(param.page, param.limit, {maxLimit: 100, defaultLimit: 20, maxPage: 2000}); // in meta block param: { ...API.plugin.pageAPI.docsParams(API), } //...