Simple API core for your projects
Useful links
- Documentation
- dc-api-cli - CLI toolkit
- dc-api-client - API client
- dc-api-mongo - Mongoose based MongoDB driver
- Examples
Dependencies
Structure
📙
├── ⚙️ controllers Request controllers
├── 🗃️ models Models for working with DB
│ └── 📁 <driver> Database driver name (Optional)
│ └── 📜 <model> Model name (js or json)
├── ️📃 config.json Configuration file
└── ⏱ startup.js Script, that was started before starting API server
Installation
0) Run npm init
or yarn init
1) Install package - npm i dc-api-core --save
or yarn add dc-api-core
2) Run npm exec dc-api-core init
or yarn dc-api-core init
3) Run npm run dc-init
or yarn dc-init
4) Run npm start
or yarn start
5) Done!
CLI
You can use dc-api-core
command locally in package.json
scripts.
Options:
- No options - Just running your project.
-
init
- Create example files and start scripts. -
--dev
- Running project in development mode. -
--cfg <path>
- Overridesconfig.json
location. You can use both relative and absolute paths.
config.json
Field | Default | Description |
---|---|---|
db |
Optional | Object |
db[driverName] |
Code of database driver | |
db[driverName].name |
Required | Database name |
db[driverName].port |
Defined by plugin | Database port |
db[driverName].user |
Optional | Database username |
db[driverName].pass |
and password | |
db[driverName].srv |
Optional for mongo | Boolean, true - use srv
|
session.secret |
Required | Private string for cookie |
session.store |
Required | Database config name |
session.ttl |
3d (3 days) |
Session lifetime in vercel/ms format |
ssl |
Optional | Enables HTTPS mode if filled |
ssl.* |
Optional | Any μWS.SSLApp options field |
ssl.key |
Required | Local path to private key |
ssl.cert |
Required | Local path to certificate file |
plugins |
[] |
Array of plugin packages names |
origin |
Origin header |
Accept requests only from this origin |
port |
8081 |
API listing port |
ws_timeout |
60 |
WebSocket request waiting timeout in seconds |
ignore |
[] |
Excluded directories in development mode |
isDev |
Read-only |
true if using --dev argument |
dev |
{} |
Config to merge if isDev is true
|
ttl |
0 |
WebSocket TTL in seconds, 0 - disabled |
Example:
{
"port": "$env", // Equals value of process.env.PORT
"db": {
"mongo": {
"host": "localhost",
"name": "test-db"
}
},
"plugins": ["dc-api-mongo"],
"session": {
"secret": "super secret string",
"store": "mongo"
},
"ssl": {
"cert": "/etc/letsencrypt/live/awesome.site/cert.pem",
"key": "/etc/letsencrypt/live/awesome.site/privkey.pem"
},
"dev": {
"port": 8081,
"db": {
"mongo": { "name": "test-dev-db" }
}
}
}
DB module
require('dc-api-core/DB'): {
[string: code]: (config?: string, template?: Object) => DBDriver
}
-
code
- Registered code of database driver. For exampledc-api-mongo
registersmongo
. -
config
- Configuration name after dot inconfig.json
. Ex.mongo('dev')
points todb['mongo.dev']
. -
template
- Object that overrides selected configuration. -
DBDriver
- Mongoose-like object (not always, defined by plugin)
Example:
const db = require('dc-api-core/DB').mongo();
Where mongo
- your database driver name.
Example:
If you're using MySQL, use mysql
as database driver (don't forget to apply plugin first).
const db = require('dc-api-core/DB').mysql();
Plugins
For first, install plugin package via npm
or yarn
.
After this add name of plugin package to plugins
array in config.json
.
Example config.json
:
{
// ...
"plugins": ["dc-api-mongo"]
}
If you want create your own plugin, read plugin development documentation
Sessions
Functions
Function | Example | Description |
---|---|---|
this.session.<name> |
this.session.name = 'User' |
Set session data |
this.session.save() |
await this.session.save() |
Save session data |
this.session.destroy() |
await this.session.destroy() |
Clear all session data |
Example
module.exports = class Controller {
async test () {
this.session.name = 'test';
await this.session.save();
this.send('saved');
}
}
Request hooks
onLoad
Will be executed before calling action method in controller.
If the onLoad
function returns false, the request will be rejected.
Example
module.exports = class Test {
onLoad () {
if (!this.session.user) return false;
}
}
Working with config.json
Require
Require config module:
const config = require('dc-api-core/config');
Get data:
config.<your_param>
Example
const config = require('dc-api-core/config');
module.exports = class Test {
index() {
this.send(config.myParam);
}
}
Routing
Register route in startup script:
// startup.js
const Router = require('dc-api-core/router');
Router.register('/testing/files/${id}/${file}.jpg', 'Test.getFile');
Now requests like /testing/files/some-id/secret_file.jpg
will call getFile
method of Test
controller.
// controllers/Test.js
class Test {
async getFile () {
this.send(this.params);
// Will send { "id": "some-id", "file": "secret_file" }
}
}
module.exports = Test;
My TODOs
- [ ] Support for glibc < 2.18
- [ ] Typing (
.d.ts
) files - [ ] Automatic package publication when all tests are passed
- [ ] More functionality tests
- [ ] Clusterization/multi-threading support