See stockpile-app for the web and mobile application that consumes this API.
The scripts below are defined in package.json.
npm startstart the app in productionnpm stopstop the app in productionnpm testtest code using Avanpm run devrun the app in developmentnpm run lintlint code using ESLint + StandardJSnpm run docsgenerate documentation using JSDoc and apiDoc
.editorconfigeditor configuration to ensure consistent indentation and line-endings.env.exampletemplate file for environment variables, should be copied and renamed to.env.jsdoc.jsonJSDoc documentation configuration.travis.ymlTravis CI configurationindex.jsmain application bootstrap file
This folder contains a file for each top-level route and routes.js, which mounts all of the routes by passing an instance of the Restify application to them.
The filenames of the controllers are the same as the top-level path they represent. For example, external-renter.js represents the group of routes starting with /external-renter.
Contains files used in the documentation providers. Documentation is generated into this folder, but is ignored by Git.
Contains the Travis deployment script. Other non-application scripts like database migrations or cron jobs belong in this directory as well.
Contains abstractions of commonly-used functionality and middleware used in the Restify application.
Contains tests for each file that requires testing. Test files should have the same name as the file they contain tests for.
Contains fixtures for tests. Fixtures for simple data can be JSON files. There should be a maximum of one fixture file per test and it should have the same name as the test file.
You must define environment variables in a .env file in the root directory of the project. Use .env.example as a template. The app will fail to start if any of the variables in .env.example are undefined.
Environment variables are loaded into the app and can be accessed in any file with process.env.VAR_NAME.
Override variables at run-time by defining them with the command, like VAR_NAME=value yarn start.
NODE_ENV=prod
PORT=9999
DB_URL=example.com
DB_USER=db-user
DB_PASSWORD=9234kjhsdfnmb234
DB_NAME=my_db
PROD_DB_URL=example.com
PROD_DB_USER=db-user
PROD_DB_PASSWORD=9234kjhsdfnmb234
PROD_DB_NAME=my_db
JWT_SECRET=392skdjlhfbjkmnb3425lkdfg
API_URL=https://example.com/api/
STRIPE_KEY=89uy345bfgnbgjbsdf
STRIPE_SECRET=345dfgdgh456hlekwhrk223
MAILGUN_KEY=key-jkhdsfhb345jbsf32345
Note that the format of DB_URL is flexible because it is passed to the Knex constructor.
Note that API_URL must begin with http:// or https:// and end with /.
Tests are located in ./test and are run asynchronously in parallel with yarn test.
Documentation is located in ./docs and is generated by running yarn run docs.
Documentation is generated by two providers: apiDoc (./docs/apidoc) and JSDoc (./docs/jsdoc).
Similar to JSDoc, but specifically intended for APIs, it uses many powerful parameters to generate documentation from docstyle comments.
Comments should be on the endpoint declaration (for example, app.get(...)), not the controller function that the endpoint uses (for example, module.exports.getAll). Configuration for the ApiDoc generator is located in package.json under the apidoc property.
The services located in ./services are documented with JSDoc. This documentation is useful when building on the API.
Configuration for the JSDoc generator is located in .jsdoc.json.
Commits to master should be made only via merged pull requests.
Each merged pull request should increment the version number in package.json using semantic versioning. This version number is used to version API endpoints, so it should be kept up to date.
When the version in package.json changes, the previous version must be added to the array of versions in index.js. This enables routes without an explicit version set to support Accept-Version headers for past versions as well as for the current version.
Each apiDoc documentation block must have an @apiVersion tag with the latest version that the route supports.
API consumers should always use an Accept-Version header with a semver string like ^1.0.0 (accept all 1.x.x releases) for the version that they are targeting.
Deployments are made via Git push to a bare remote repository on the server. A post-receive hook runs every time a push is made to the repository, copying the new files to the web root, restarting the server, and generating documentation. This is the script:
APP_DIR=/var/www/stockpile-api
printf "Copying files..."
GIT_WORK_TREE="$APP_DIR" git checkout -f
printf " %s\n" "Done."
cd "$APP_DIR"
printf "Installing dependencies..."
yarn install
printf "Restarting app..."
npm restart
printf " %s\n" "Done."
printf "Generating docs..."
yarn run docs
printf " %s\n" "Done."