Nifty Procrastination Machine

    express-api-versioning

    2.0.0 • Public • Published

    Build Status Coverage Status Code Climate Test Coverage Issue Count

    Express API Versioning

    Express API versioning is an express middleware that dynamically loads different API versions seamlessly depending on the version number specified in the request url.

    It is written in Javascript ES6 syntax and it is further transpiled down to Javascript ES5 using babel.

    What's new in v2

    • Version 2 introduces a new way to resolve errors using callback instead of the try and catch block.

    Installation

    • npm install express-api-versioning --save
    • express is required as a peer dependency.

    Usage

    Using ES6

    import expressApiVersioning from 'express-api-versioning';

    Using ES5

    const expressApiVersioning = require('express-api-versioning');

    app.use(expressApiVersioning({
      apiPath: path.join(__dirname, './api'),// absolute path to the api directory
      test: /\/api\/(v[0-9]+).*/, // regular expression to get the version number from the url
      entryPoint: 'index.js', // entry point exports a function which takes an instance of express as parameter.
      instance: app // passes an instance of express to the entry point
    }, (error, req, res, next) => {
     // Do something here with the error
     next(); // calls the next middleware
    }));

    Error Handling

    As of v2, the middleware returns an error object as the first parameter of the callback and has properties code and message.

    The middleware will throw an error when;

    1. the apiPath is not specified
    2. an express instance is not specified and not a function
    3. the api version cannot be found in the api directory.

    Error Code

    S/N Code Message
    1. 101 You must explicitly specify a path to where the APIs reside
    2. 102 You must explicitly set an instance of express
    3. 103 Entry point not Found
    4. 104 No version number found
    5. 105 An instance of express must be a function but got type ${typeof instance}

    Issue Reporting

    Please use the issues page to report an issue.

    API References

    Express API Versioning is highly customizable and does not introduce complexities to your application folder structure. It takes a configuration object as parameter.

    Configuration item Default Description
    test /\/api\/(v[0-9]+).*/ Regular expression to get the version number from the request url. It gets the version number from the first group of the regex match.
    entryPoint app.js Entry point for each api version. It exports a function which takes an instance of express as parameter.
    apiPath empty string Absolute path to each api version container/directory. This is usually path.join(__dirname, './api').
    instance null An instance of express app which will be passed down to the entry point for usage.

    Todo

    • Create a boilerplate for Express API Versioning with Sequelize as ORM

    Author

    Temitayo Fadojutimi is a Software Developer at Andela and he dedicates his expertise to solving practical problems in the society. He tweets at @adesege_

    Testing

    To test this package,

    • Clone this repo or npm install express-api-versioning
    • cd into the package directory and run npm install
    • Then run npm test to run the test.

    Contributing

    Thank you for your interest in contributing to this package. I currently accept contributions from everyone but I expect that standards are maintained. To contribute,

    1. Fork the project
    2. Create a feature branch, branch away from master
    3. Write tests, using Mocha and Chai or any other testing frameworks, and code
    4. If you have multiple commits please combine them into a few logically organized commits by squashing them
    5. Push the commit(s) to your fork
    6. Submit a merge request (MR) to the master branch
    7. The MR title should describe the change you want to make
    8. The MR description should give a motive for your change and the method you used to achieve it.
    9. Mention the issue(s) your merge request solves, using the Solves #XXX or Closes #XXX syntax to auto-close the issue(s) once the merge request will be merged.
    10. Be prepared to answer questions and incorporate feedback even if requests for this arrive weeks or months after your MR submission
    11. If a discussion has been addressed, select the "Resolve discussion" button beneath it to mark it resolved.
    12. When writing commit messages please follow these guidelines.

    Install

    npm i express-api-versioning

    DownloadsWeekly Downloads

    121

    Version

    2.0.0

    License

    MIT

    Last publish

    Collaborators

    • adesege