@byu-oit/byuapi

Starter for NodeJS BYU APIs.

Stats

StarsIssuesVersionUpdatedCreatedSize
@byu-oit/byuapi
0.0.134 years ago4 years agoMinified + gzip package size for @byu-oit/byuapi in KB

Readme

byuapi

DO NOT INSTALL THIS PACKAGE YET, KEEP READING...

Although this package does provide some tooling to slightly reduce the amount of code written (3 line difference), it is best to NOT INCLUDE this package as a dependency but instead to include just the dependencies your project needs.

The Tech Stack

  • Swagger - We use the swagger specification version 2. With swagger we define an API, including its interfaces and schemas, through a YAML or JSON file.

  • Sans-Server - We use sans-server, a serverless library that is similar to express although much lighter and it does not integrate directly with NodeJS' native http module. This improves development time by making it easier to write tests and tests run faster because there is no http traffic involved.

  • Sans-Server-Swagger - The sans-server-swagger library is a piece of sans-server middleware that performs multiple operations: 1) routing, 2) input deserialization, 3) input validation, 4) response validation, and 5) mocking. This library makes it easy to get your API up and running with only a swagger document (via mocked responses).

  • Sans-Server-Express or Sans-Server-Lambda are used to provide an integration to either express on an AWS EC2 or AWS EBS, or to AWS Lambda.

How To

You can copy the example directory included with this project and use it as a starter, or you can follow these steps:

  1. Create a directory for your application to place all of your application's files.

  2. Create a swagger file using swagger specification version 2 that represents your API.

  3. Create the api sans-server instance:

    api.js

    const SansServer        = require('sans-server');
    const SansServerSwagger = require('sans-server-swagger');
    
    // create a sans-server instance and export it
    const api = SansServer();
    module.exports = api;
    
    // add swagger middleware to the sans-server instance.
    api.use(SansServerSwagger({
        controllers: './controllers',
        development: true,
        swagger: './swagger.json'
    }));
    
  4. Test your API.

    test/api.js

    const api       = require('../api');
    const expect    = require('chai').expect;
    const path      = require('path');
    const swagger   = require('sans-server-swagger');
    
    describe('api', () => {
    
        beforeEach(() => console.log('\n'));
    
        it('response examples are valid', () => {
            return swagger.testSwaggerResponseExamples(path.resolve(__dirname, '../swagger.json'))
                .then(results => expect(results.percentage).to.equal(1));
        });
    
        it('GET /v1/pets', () => {
            return api.request({ method: 'GET', path: '/v1/pets' })
                .then(res => {
                    expect(res.body).to.equal('[]');
                });
        });
    
    });
    
  5. Create your controllers. https://github.com/byu-oit/sans-server-swagger#controllers

  6. Create an express integration or a lambda integration.

    Express Example

    const api               = require('./api');
    const bodyParser        = require('body-parser');
    const express           = require('express');
    const expressTranslator = require('sans-server-express');
    
    // create an express app
    const app = express();
    
    // add the body parser middleware - only needed if the API will accept JSON bodies in the request
    app.use(bodyParser.json());
    
    // integrate sans-server instance with express
    app.use(expressTranslator(api));
    
    // start the server listening
    app.listen(port, function(err) {
        if (err) {
            console.error(err.stack);
            process.exit(1);
        } else {
            console.log('Server listening on port ' + port);
        }
    });
    

    Lambda Example

    const api               = require('./api');
    const lambdaTranslator  = require('sans-server-aws-lambda');
    
    exports.handler = lambdaTranslator(api);
    

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.