stockpile-co / api
The API for Stockpile, an app that manages stuff for organizations.
See stockpile-app for the web and mobile application that consumes this API.
The scripts below are defined in
npm startstart the app in production
npm stopstop the app in production
npm testtest code using Ava
npm run devrun the app in development
npm run lintlint code using ESLint + StandardJS
npm 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
.jsdoc.jsonJSDoc documentation configuration
.travis.ymlTravis CI configuration
index.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
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
Override variables at run-time by defining them with the command, like
VAR_NAME=value yarn start.
Example Environment Variables
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.
API_URL must begin with
https:// and end with
Tests are located in
./test and are run asynchronously in parallel with
Documentation is located in
./docs and is generated by running
yarn run docs.
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
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
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."