1 | # Node.js Express restful JSON API seed
|
2 |
|
3 | [![npm version](https://badge.fury.io/js/nodejs-restful-jsonapi-seed.svg)](https://badge.fury.io/js/nodejs-restful-jsonapi-seed) [![](https://img.shields.io/npm/dm/nodejs-restful-jsonapi-seed.svg)](https://www.npmjs.com/package/nodejs-restful-jsonapi-seed) [![Build Status](https://api.travis-ci.com/nuxy/nodejs-restful-jsonapi-seed.svg?branch=master)](https://app.travis-ci.com/github/nuxy/nodejs-restful-jsonapi-seed)
|
4 |
|
5 | Everything you need to start building a scalable web application.
|
6 |
|
7 | ![the "seed" app](https://raw.githubusercontent.com/nuxy/nodejs-restful-jsonapi-seed/master/package.png)
|
8 |
|
9 | ## Features
|
10 |
|
11 | - ECMAScript 2022 (ES6) compatible.
|
12 | - RESTful application interface.
|
13 | - JSON API standard request/responses.
|
14 | - ABAC (Attribute-Based Access Control)
|
15 | - HTTP/1/2 and SSL support.
|
16 | - Database driver support.
|
17 | - Session handling using cookies.
|
18 | - Schema-based validation.
|
19 | - Stream-based logging and file rotation.
|
20 | - Production process manager.
|
21 | - JSDoc App/Swagger API documentation.
|
22 | - Deployable as a Docker service.
|
23 |
|
24 | ## Dependencies
|
25 |
|
26 | - [Node.js](https://nodejs.org)
|
27 | - [Docker](https://docker.com) (optional)
|
28 |
|
29 | ## Installation
|
30 |
|
31 | ### seed-cli
|
32 |
|
33 | Install the command-line utility using [NPM](https://npmjs.com).
|
34 |
|
35 | $ npm install -g nodejs-restful-jsonapi-seed
|
36 | $ seed-cli --help
|
37 |
|
38 | Usage: seed-cli [options]
|
39 |
|
40 | Options:
|
41 | --create <project-name> Create a new seed example project
|
42 | --start Launch a single server instance
|
43 | --deploy Launch a server cluster
|
44 | --watch Launch the server (development mode)
|
45 | --lint Run ESLint on project sources
|
46 | --test Run Mocha integration tests
|
47 | --docker Deploy your application as a Docker service
|
48 | --genapi Generate Swagger definitions
|
49 | --gendoc Generate documentation using JSDoc
|
50 | --env <environment> Set the NODE_ENV (default: development)
|
51 | -h, --help output usage information
|
52 |
|
53 | ### Manual
|
54 |
|
55 | Clone the repository, or download the latest [release](https://github.com/nuxy/nodejs-restful-jsonapi-seed/releases).
|
56 |
|
57 | $ git clone https://github.com/nuxy/nodejs-restful-jsonapi-seed.git
|
58 |
|
59 | Install package dependencies using [NPM](https://npmjs.com).
|
60 |
|
61 | $ npm install
|
62 |
|
63 | ## Developers
|
64 |
|
65 | While `seed-cli` provided with this package can execute NPM scripts, it's not a requirement. You can also achieve this using [npm-run-script](https://docs.npmjs.com/cli/run-script).
|
66 |
|
67 | ### CLI options
|
68 |
|
69 | Set your environment. If `NODE_ENV` is not defined, the default config `development` is used.
|
70 |
|
71 | $ export NODE_ENV=<production|staging|qa>
|
72 |
|
73 | Launch a _single server instance_:
|
74 |
|
75 | $ npm run start
|
76 |
|
77 | Launch a _server cluster_:
|
78 |
|
79 | $ npm run deploy
|
80 |
|
81 | Launch the server (development mode) with [nodemon](https://nodemon.io):
|
82 |
|
83 | $ npm run watch
|
84 |
|
85 | Run [ESLint](https://eslint.org) on project sources:
|
86 |
|
87 | $ npm run lint
|
88 |
|
89 | Run [Mocha](https://mochajs.org) integration tests:
|
90 |
|
91 | $ npm run test
|
92 |
|
93 | Deploy your application as a [Docker](https://docker.com) service:
|
94 |
|
95 | $ npm run docker
|
96 |
|
97 | Generate [Swagger](https://swagger.io) definitions:
|
98 |
|
99 | $ npm run genapi
|
100 |
|
101 | Generate documentation using [JSDoc](https://jsdoc.app):
|
102 |
|
103 | $ npm run gendoc
|
104 |
|
105 | ## API Examples
|
106 |
|
107 | The following [routes](src/routes/examples) have been enabled in the application. When the server is running in _development_ mode [Swagger](https://swagger.io) generated documentation can be accessed at: [http://localhost:3000/api-doc](http://localhost:3000/api-doc)
|
108 |
|
109 | ## Documentation
|
110 |
|
111 | When the server is running in _development_ mode [JSDoc](https://jsdoc.app) generated documentation can be accessed at: [http://localhost:3000/app-doc](http://localhost:3000/app-doc)
|
112 |
|
113 | ## Enabling HTTP/2
|
114 |
|
115 | The [http2](https://nodejs.org/api/http2.html) module is an experimental API which relies on the [Latest Current Version](https://nodejs.org/en/download/current) of Node.js to work. Furthermore, since there are no browsers known that support unencrypted HTTP/2, the use of [X.509 certificates](https://en.wikipedia.org/wiki/X.509) is necessary when communicating with browser clients.
|
116 |
|
117 | To set-up the server, first you must generate the certificate and key files:
|
118 |
|
119 | $ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -keyout localhost-key.pem -out localhost-cert.pem
|
120 |
|
121 | See the [Node.js documentation](https://nodejs.org/api/http2.html#http2_client_side_example) for information regarding client-side set-up.
|
122 |
|
123 | ## SSL configuration
|
124 |
|
125 | Depending on your application requirements there are multiple ways to set-up the [server config](https://github.com/nuxy/nodejs-restful-jsonapi-seed/blob/master/config/default.json#L49):
|
126 |
|
127 | ### Absolute path
|
128 |
|
129 | If your certificates are installed in a location outside of the application scope (e.g. `/etc/ssl/certs`), and your application has the permissions to access these files, you can add the _absolute path_ to the respective configuration values.
|
130 |
|
131 | ### String output
|
132 |
|
133 | If, for whatever reason, you cannot host the certificates locally (shared environment), you can output each file as a newline-delimited string using the following command and add the _string output_ to the respective configuration values.
|
134 |
|
135 | $ cat localhost-<key|cert>.pem | perl -pe 's/\n/\\n/g'
|
136 |
|
137 | ## Common questions
|
138 |
|
139 | > What was your motivation for creating this package?
|
140 |
|
141 | I wanted a package that was lightweight and provided all of the Production features needed to create a scalable API server. While there are many packages available, most are lacking or require you to sacrifice simplicity or features for little gain.
|
142 |
|
143 | This package provides _everything_ you need to quickly build your application using a consistent and secure set of standards.
|
144 |
|
145 | > How do you set-up this package to use a custom database?
|
146 |
|
147 | You can update the [database wrapper](https://github.com/nuxy/nodejs-restful-jsonapi-seed/blob/master/src/lib/Database.js) example to use any [DBMS](https://www.npmjs.com/search?q=dbms) package available while extending the application [SessionStore](https://github.com/nuxy/nodejs-restful-jsonapi-seed/blob/master/src/lib/SessionStore.js) to use a compatible [Connection Session Store](https://github.com/expressjs/session#compatible-session-stores) module.
|
148 |
|
149 | ## Windows support
|
150 |
|
151 | This package has limited support for Windows due to cross-platform compatibility issues, most notably `SHELL` environment differences. Due to this, you can either run this package in [Docker](https://docker.com) or switch to a UNIX-like operating system.
|
152 |
|
153 | ## Contributions
|
154 |
|
155 | If you fix a bug, or have a code you want to contribute, please send a pull-request with your changes. (Note: Before committing your code please ensure that you are following the [Node.js style guide](https://github.com/felixge/node-style-guide))
|
156 |
|
157 | ## Versioning
|
158 |
|
159 | This package is maintained under the [Semantic Versioning](https://semver.org) guidelines.
|
160 |
|
161 | ## License and Warranty
|
162 |
|
163 | This package is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
|
164 |
|
165 | _nodejs-restful-jsonapi-seed_ is provided under the terms of the [MIT license](http://www.opensource.org/licenses/mit-license.php)
|
166 |
|
167 | ## Author
|
168 |
|
169 | [Marc S. Brooks](https://github.com/nuxy)
|