NodeJS Blog API

Blog API developed by Bytecode Digital Agency as free (as in freedom) open source software. Built in NodeJS. Available as a standalone server, or as a NPM package

Installation

To install the module, run

yarn add nodejs-blog

or

npm install nodejs-blog

For contributing to the development, fork the GitHub repository.

Configuration

This part is not implemented in the code yet.

To use the NodeJS Blog module, first, import the package

const nodeBlog = require('nodejs-blog');
const { authors, auth, users, categories, articles } = require('nodejs-blog');

to start using the package, create a new blog object:

const client = 'YOUR_DB_CLIENT'; // for more info, see https://knexjs.org/
const host = 'YOUR_DB_HOST';
const database = 'YOUR_DB_NAME';
const user = 'YOUR_DB_USER';
const pass = 'YOUR_DB_PASS';
const debug = true || false;

const blog = nodeBlog(client, host, user, database, password, debug);

For authentication you should set the following environment (process.env.[variable] = value) variables, or the auth methods will not work:

SALT_ROUNDS=number
JWT_SECRET=string
JWT_EXPIRES_IN_DAYS=number_of_days

Then you can use the imported functions as you wish, for example:

const posts = await articles.list(blog);

Just send the blog instance as the first argument and the rest of the arguments second. This is because this way the same logic can be applied to multiple blog instances within an application.

The available methods are:

authors.list(blog)
authors.get(blog, id)
authors.add(blog, authorObject)
authors.modify(blog, id, modifiedData)
authors.delete(blog, id)

auth.authenticate(blog, username, password) // Returns true/false
auth.generateToken(blog, username, password) // Returns JWT, throws error if invalid credentials
auth.decode(jwt) // Returns decoded object
auth.validate(blog, username, password) // Returns true/false

users.list(blog)
users.get(blog, id)
users.add(blog, userObject)
users.modify(blog, id, modifiedData)
users.delete(blog, id)

categories.list(blog)
categories.get(blog, id)
categories.add(blog, categoryObject)
categories.modify(blog, id, modifiedData)
categories.delete(blog, id)

articles.list(blog)
articles.get(blog, id)
articles.add(blog, articleObject)
// articles.modify(blog, id, modifiedData) // not available yet
articles.delete(blog, id)

We recommend creating a single file that will create the NodeBlog instance, and export this instance, and import in all other files where you want to use NodeJS Blog.

For security reasons we recommend using environment variables for loading the configuration. This is also in compliance with the 12 factor app Config guidelines.

Note: NodeJS blog was made to be used with PostgreSQL, but it should(/could) also be compatible with other databases, as it uses KnexJS under the hood.

A demo application and a standalone CLI are currently in development

Running the API as a standalone service (still in development, might not work 100%)

First clone the repository and cd into the directory.

To run NodeJS Blog as a standalone service, run cp .env.example .env to create the .env file.

Set your database details and preferences in the .env file and run yarn run start.

The API documentation can be generated using SwaggerUI. The contents can be found in ./swagger.yml.

For authentication, add a Authorization header, with a bearer token, following the Bearer [jwt-token] convention.

Development

For development, the following commands are available:

Command	Functionality
yarn run dev	Runs a nodemon server for the server/server.js file, and exposing the standalone service to your localhost
yarn run cli	Runs the CLI tool created for simple CRUD operations without accessing the database directly
yarn run lint	Runs ESLint, for PRs this should always pass
yarn run test	Runs Jest once, for PRs this should always pass. Your database must be available as it is used to run tests on (beware: all existing data will be wiped, we recommend using a separate test-database, this can be set in the .env file)
yarn run test:watch	Same as yarn run test, but it Jest watches for changes
yarn run coverage	Creates coverage report, for this the test database should also be available
yarn run migrate	Migrates your database (normal one, not test database) to the most recent migration, seeds will not be ran
yarn run reinstall	Deletes the node_modules/ folder and reinstalls everything, if you get some stange dependency errors, run this command
yarn run clean	Deletes folders build/, dist/ and coverage/

Node Environments

The following NodeJS Environments are integrated:

Env	Effect
development	Will add development headers, and improve logging experience
test	Will use test database, should only be used for automatic testing
production	Production mode