This is a node.js application powered by Express that provides the main functions to interact with water meter signals.
You can visit it on http://console.citytaps.org
We use Node.js and Bookshelf.js (a MySQL ORM) as our main technologies.
Node.js is a great and modern engine with a huge community of module creators.
Bookshelf.js is among the most popular of the Node.js ORM packages. It stems from the Knex.js, which is a flexible query builder that works with MySQL and SQLite3.
The first step is obviously to install the development dependencies.
On GNU/Linux, just install Git with your package manager or:
apt-get install git
On Mac OS, download the software here:
http://git-scm.com/download/mac
To check if git is installed:
git --version
Installing Node.js on your local environment is necessary to run CityTaps API.
You can find detailed instructions of installation on the official page.
After install, make sure to run npm install and npm start.
The easiest way is to open up a terminal and type the installation command below:
$ git clone [email protected]:Citytaps/ct-cloud-API.git
$ cd ct-cloud-API
$ npm install
$ npm startThe platform is made of 3 main components:
The Models is where all data is stored and ready to be used. It is being handled by Bookshelf.js which is an MySql ORM.
All the bodies responses are encoded in JSON and all the data you send along request should be encoded in JSON.
You will find HTTP status code for the response, here is what they mean:
- 200: success
- 201: success (and something has been created)
- 204: success (and something has been deleted)
- 307: no data for next row (in pagination)
- 400: bad request
- 401: not authenticated
- 403: forbidden (authenticated but not enough permissions)
- 404: table not found
- 409: document already exists
- 500: internal server error
All the requests that mention "Requires authentication and authorization" are likely to send 401 and 403 if the conditions are not met.
Please check the apiDOC to have deeper understanding of how each routes work.
Authentication is based on a token.
We can now introduce the application files structure.
- authentification
- controller
- helper
- lib
- models
- package.json
- test
A controller is a set of handlers attached to a route. When a request matches a route, the handler is executed.
We can also check the official (Express.js documentation)[http://expressjs.com/en/guide/routing.html] about routing if we want to learn more about it, or keep it as a reference for future use.
You may wonder how to glue everything together. All that magic is done in server.js. The code itself is straightforward.
Models are used to interact with the database. They represent the data our application needs.
For info on Knex config JSON, see how to install.
Then, your module object contains the CT models and a Bookshelf element.
To create a migration file:
knex migration:make [name]
To apply all the migration files:
knex migration:latest
To rollback the lastet migration:
knex migration:rollback
See: http://knexjs.org/#Migrations
The node_modules/ folder contains the dependencies installed. package.json is needed to keep the dependencies the application needs
Unit test using Tape (see https://github.com/substack/tape).
Tests are defined in the test/ folder.
Tests can be run with
```npm test```
Or with Nodemon
```npm run devtest```
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using npm run devtest.
- Create an issue on Trello and describe your idea
- Create your feature branch (
git checkout -b [#link_of_the_trello_card]) - Commit your changes (
git commit -am 'Add some feature') - Publish the branch (
git push origin my-new-feature) - Create a new Merge Request
- Profit! ✅