Vidatio - API

Folder Structure

api
 ├── .editorconfig
 ├── .gitignore
 ├── .git
 │     ├──*
 │     *
 ├── app.coffee
 ├── app.js
 ├── coffeelint.json
 ├── Gulpfile.coffee
 ├── Gulpfile.js
 ├── package.json
 ├── README.md
 ├── logs
 │    ├── access.log
 │    ├── api.log
 │    └── penguins.log
 ├── modules
 │    ├── _apidoc                           
 │    │    ├── auth.coffee
 │    │    ├── footer.md
 │    │    ├── header.md
 │    │    └── permissions.coffee
 │    ├── api
 │    │    ├── connection.coffee
 │    │    ├── index_apitest.coffee
 │    │    ├── index.coffee
 │    │    └── penguins
 │    │         ├── _apidoc.coffee
 │    │         ├── index_apitest.coffee
 │    │         ├── index.coffee
 │    │         └── penguin.coffee
 │    ├── config.coffee
 │    ├── config.coffee.example
 │    ├── index_apitest.coffee
 │    ├── index.coffee
 │    ├── index_test.coffee
 │    └── logger.coffee
 ├── build
 │    ├──*
 │    *
 └── docs
      ├──*
      *

Unit Tests

All test files are in the same folder where the FUT (file under test) is, if you want to test the file appleJuiceMaker.js, the corresponding test file have to be appleJuiceMaker_test.js.

In this setup, Jasmine is used for testing.

Api tests

Frisby.js is used for Api Tests, same naming conventions apply for Api Tests like for Unit Tests except that they end with _apitest.js.

Debug

Node-Inspector is the debugging tool of choice, by default gulp dev starts the app in debug mode and Node-Inspector.

Docs

APIDOC - see homepage for details, can be generated with gulp docs, target directory is ./docs. Take a look at the apidoc part in the package.json file.

Gulp

Self-explanatory. Here's the output from gulp help:

Usage
  gulp [task]

Available tasks
  build                Lints and builds the project to './build'.
  clean                Delete './build' folder.
  clean:docs           Delete './docs' folder.
  debug                Starts the app and the debugger.
  default              Runs 'develop' and 'test'.
  dev                  Shorthand for 'develop'.
  develop              Runs 'build' and watches the source files, rebuilds and starts tests on change, starts the debugger.
  docs                 Generate apidoc.
  help                 Display this help text.
  lint                 Lints all CoffeeScript source files.
  nodemon              Starts the app with Nodemon.
  run                  Run the App.
  sleep                Sleep Helper.
  test                 Perform unit and API tests.
  test:api             Perform all API tests.
  test:api:standalone  Perform API tests (standalone).
  test:unit            Perform all unit tests.

Logging

Bunyan is a simple logger, use (Log.io)[https://github.com/NarrativeScience/Log.io] for real-time logging in your browser - works great.

Linting

There's a CoffeeScript Style Guide, you can modify the coffeelint.json file for your needs (e.g. 4 spaces instead of 2).

EditorConfig

The .editorconfig contains all relevant styles for your editor, your IDE/Editor should support it, otherwise install a plugin from editorconfig.org.

Some thoughts

The application is designed in a highly modularized way.

The modules folder contains the main application, it should serve the API.
- config.coffee/config.coffee.example ⇒ the config.coffee file isn't included in the repository
- index.coffee ⇒ exports a function, which starts the server
- logger.coffee ⇒ here's the place, where the loggers are defined. In this case the logger and some logger specific routes (e.g. to change the log level of a router) are exported. The loggers are defined here because this makes other sub-modules like the api independent of the used logger, just make sure that these logging functions are implemented:
  - fatal
  - error
  - warn
  - info
  - debug
  - trace
The _apidoc folder is used to store apidoc files which doesn't fit anywhere else, like footer.md.
The API is designed as middleware for express.js, this means that a simple app.use require("./api") is everything you have to do.
- Within the api folder there is a separate folder for each REST Ressource, e.g. penguins which contains following files:
  - _apidoc.coffee ⇒ apidoc specifications from older versions should be moved here (to enable comparison between api versions)
  - index.coffee ⇒ exports the routes for single and multiple Resource (penguin / penguins).
  - index_apitest.coffee ⇒ self-explanatory
  - penguin.coffee ⇒ Mongoose Schema, Model

vidatio/api