@byu-oit/byuapi

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.

   • You can specify the controller and function each path should use by specifying the x-controller and operationId properties. See https://github.com/byu-oit/sans-server-swagger#controllers for more details.

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);