orion-api

Orion allows you to build a REST API app in just a few lines of code. This library is to be used in combination with Node and Express. It sets up all the necessary CRUD data endpoints, file uploads, authentication endpoints, and error handling.

The latest version of the library supports the following components:

• Database: SQL Server
• Storage: Azure Blob Storage
• Third Party Auth: Facebook
• Monitoring: Azure Application Insights

In this documentation:

• Getting Started
• Configuration
• Client Usage
  • Data Endpoints
  • File Uploads
  • Authentication
  • Error logging
• License

Getting Started

1. Set up a folder for your NodeJS application.
2. Install Express and Orion to your application and save it to package.json.

   $ npm install --save express
   $ npm install --save orion-api
   

3. Create a configuration module. Please see the configuration section below for more details.
4. (Optional) Set up database tables based on the configuration you created (if you haven't), using Orion's setup.js. The script is located at the root path of the Orion module source code. It takes the configuration file path and the output file path as arguments.

   $ node node_modules/orion-api/setup.js ./config.js ./setup.sql
   

   The above command will create a SQL server query file named setup.sql that you can run on the database server to set up the tables.
5. Set up server.js for the application entry point. Import Express, Orion, and the configuration module you created, and set up the application as follows:

   var express = require('express');
   var orion = require('orion-api');
   var config = require('./config');
   
   var app = new express();
   orion.setConfig(config);
   orion.setupApiEndpoints(app);
   orion.startApiApp(app);
   

6. You're all set up! You can now run server.js to see your app in action. Unless you specify a port in the startApiApp() call, you will see your app running at port 1337.

   $ node server.js 
   

Configuration

A configuration module is required to give the application the necessary information about your project. This module should specify the connection strings, authentication and authorization settings, user roles and access levels, and most importantly, the data models.

Below is the structure of a configuration module, with description for each property.

module.exports = 
{
    // (Required) Secret key string for authentication purposes.
    secretKey: __SECRETKEY__,

    // (Required) Salt string for encrypting passwords.
    salt: __SALT__,

    // (Required) Database connection string.
    databaseConnectionString: __DB_CONNECTION_STRING__,

    // (Optional) Azure Blob Storage connection string. Required if you want to support 
    // file upload. Set to null if not applicable.
    storageConnectionString: __STORAGE_CONNECTION_STRING__,

    // (Optional) Azure Blob Storage account name. Required if you want to support 
    // file upload. Set to null if not applicable.
    storageContainerName: __STORAGE_CONTAINER_NAME__,

    // (Optional) Azure Application Insights key. Required if you want to support 
    // monitoring. Set to null if not applicable.
    appInsightsKey: __APPLICATION_INSIGHTS_KEY__,

    // (Optional) Facebook app secret. Required if you want to support Facebook 
    // authentication. Set to null if not applicable.
    facebookAppSecret: __FACEBOOK_APP_SECRET__,

    // (Optional) Facebook app ID. Required if you want to support Facebook 
    // authentication. Set to null if not applicable.
    facebookAppId: __FACEBOOK_APP_ID__,

    // (Required) Requirements for new user passwords
    passwordReqs:
    {
        // (Required) Minimum character length
        minLength: 8,

        // (Required) Whether or not the password should have an uppercase character.
        uppercaseChar: false,

        // (Required) Whether or not the password should have an lowercase character.
        lowercaseChar: false,

        // (Required) Whether or not the password should have a digit character.
        digitChar: false,

        // (Required) Whether or not the password should have a special character.
        specialChar: false
    },

    // (Required) Array of user roles.
    // "guest" and "owner" are special user roles that don't need to be included in this list.
    // "guest" role is given to an unauthenticated user, and "owner" role is given to an 
    // authenticated user who is requesting a resource that they own.
    roles: ["member", "admin"],

    // (Required) Default role assigned to authenticated user after signing up.
    defaultRole: "member",

    // (Required) List of data entities/tables
    entities:
    {
        "asset":
        {
            fields:
            {
                "id": { type: "id", isEditable: false, createReq: 0, foreignKey: null },
                "ownerid": { type: "int", isEditable: false, createReq: 0, foreignKey: { foreignEntity: "user", resolvedKeyName: "owner" }},
                "filename": { type: "string", isEditable: true, createReq: 2, foreignKey: null }
            },
            readConditionStrings: [{ roles: ["owner", "admin"], fn: function(u) { return ""; } }],
            validators:
            {
                create: [{ roles: ["member"], fn: function(n) { return true; } }],
                update: [],
                delete: [{ roles: ["owner", "admin"], fn: function(o) { return true; } }]
            }
        },
        "user":
        {
            fields:
            {
                "id": { type: "id", isEditable: false, createReq: 0, foreignKey: null },
                "domain": { type: "string", isEditable: false, createReq: 0, foreignKey: null },
                "domainid": { type: "string", isEditable: false, createReq: 0, foreignKey: null },
                "roles": { type: "string", isEditable: false, createReq: 0, foreignKey: null },
                "username": { type: "string", isEditable: true, createReq: 2, foreignKey: null },
                "password": { type: "secret", isEditable: false, createReq: 2, foreignKey: null },
                "email": { type: "string", isEditable: true, createReq: 2, foreignKey: null },
                "firstname": { type: "string", isEditable: true, createReq: 2, foreignKey: null },
                "lastname": { type: "string", isEditable: true, createReq: 2, foreignKey: null },
                "createdtime": { type: "timestamp", isEditable: false, createReq: 0, foreignKey: null }
            },
            readConditionStrings: [{ roles: ["member", "owner", "admin"], fn: function(u) { return ""; } }],
            validators:
            {
                create: [{ roles: ["guest"], fn: function(n) { return true; } }],
                update: [{ roles: ["owner", "admin"], fn: function(u, o, n) { return true; } }],
                delete: [{ roles: ["admin"], fn: function(o) { return true; } }]
            }
        },
        "item":
        {
            fields:
            {
                "id": { type: "id", isEditable: false, createReq: 0, foreignKey: null },
                "ownerid": { type: "int", isEditable: false, createReq: 0, foreignKey: { foreignEntity: "user", resolvedKeyName: "owner" }},
                "name": { type: "string", isEditable: true, createReq: 2, foreignKey: null },
                "date": { type: "int", isEditable: true, createReq: 2, foreignKey: null },
                "createdtime": { type: "timestamp", isEditable: false, createReq: 0, foreignKey: null }
            },
            readConditionStrings: [{ roles: ["owner", "admin"], fn: function(u) { return ""; } }],
            validators:
            {
                create: [{ roles: ["member"], fn: function(n) { return true; } }],
                update: [{ roles: ["owner", "admin"], fn: function(u, o, n) { return true; } }],
                delete: [{ roles: ["owner", "admin"], fn: function(o) { return true; } }]
            }
        },
        "message":
        {
            fields:
            {
                "id": { type: "id", isEditable: false, createReq: 0, foreignKey: null },
                "ownerid": { type: "int", isEditable: false, createReq: 0, foreignKey: { foreignEntity: "user", resolvedKeyName: "owner" }},
                "recipientid": { type: "int", isEditable: false, createReq: 2, foreignKey: { foreignEntity: "user", resolvedKeyName: "recipient" }},
                "text": { type: "string", isEditable: false, createReq: 2, foreignKey: null },
                "flagged": { type: "boolean", isEditable: true, createReq: 0, foreignKey: null },
                "createdtime": { type: "timestamp", isEditable: false, createReq: 0, foreignKey: null }
            },
            readConditionStrings:
            [
                { roles: ["member"], fn: function(u) { return "ownerid=" + u + "|recipientid=" + u; } },
                { roles: ["admin"], fn: function(u) { return ""; } }
            ],
            validators:
            {
                create: [{ roles: ["member"], fn: function(n) { return true; } }],
                update: [{ roles: ["member", "admin"], fn: function(u, o, n) { return u === o.recipientid; } }],
                delete: [{ roles: ["admin"], fn: function(o) { return true; } }]
            }
        }
    }
};

Client Usage

Data Endpoints

File Uploads

Authentication

Error Logging

License

(The MIT License)

Copyright (c) 2017 Christopher Tjong [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.