https://github.com/human-connection/human-connection-clock-api
Nodejs api for Human Connection Clock
https://github.com/human-connection/human-connection-clock-api
Last synced: 12 months ago
JSON representation
Nodejs api for Human Connection Clock
- Host: GitHub
- URL: https://github.com/human-connection/human-connection-clock-api
- Owner: Human-Connection
- License: mit
- Created: 2018-09-20T11:21:28.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-08-03T19:03:35.000Z (almost 5 years ago)
- Last Synced: 2025-06-30T11:03:14.461Z (12 months ago)
- Language: EJS
- Homepage:
- Size: 1.13 MB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Human Connection Clock - API Server (Backend)
This repository contains the API Server - or in other terms Backend - of the Human Connection Clock.
To find out more about the Human Connection Clock and Human Connection - the network behind it - visit https://human-connection.org/en/.
## Tech Stack
* Node.js: The API Server is running on [Node.js](https://nodejs.org/en/) - a JavaScript runtime environment for server-side scripting
* Express.js: We use the [Express.js](https://expressjs.com/en/) framework - a Node.js framework to help build web applications
* Nodemon: We use [Nodemon](https://nodemon.io/) for development - a handy replacement wrapper for Node.js that automatically restarts the application on file changes
* MySQL: We use [MySQL](https://www.mysql.com) as our relational database of choice to store our data
* MailHog: We use [MailHog](https://github.com/mailhog/MailHog) to debug and preview the email communication
## Project Structure & Components
**PROJECT STRUCTURE / DIRECTORIES**
* server.js: The starting point for this Node.js application which starts the server
* core/: The core directory contains the most important files of the project like database, mailer, router and main controller
* core/entryController.js: Is the main controller for all the requests
* core/restapi.js: All routes can be found here, they will also be listed further down
* documentation/: Documentation for the Human Connection Clock API
* mails/: The mails directory holds the mail templates
* migrations/: Migrations for the database
* public/: The public directory is not used for now
**DATABASE**
We use MySQL for the COC API as our relational database.
Currently all of the database related code can be found in the `core/db.js` file.
This includes the credentials for the database (host, user, password and db name) and can be changed in this file.
MySQL DB can be configured with the following environment variables:
| Variable | Description |
|--------------|-------------------------------|
| `MYSQL_HOST` | Host address for the database |
| `MYSQL_DB` | Database Name |
| `MYSQL_USER` | MySQL User |
| `MYSQL_PASS` | MySQL Password |
Currently we have two tables:
* apikeys: Contains the apikeys required to perform authorized API request
* entries: Stores the user entries for the Human Connection Clock
For more information about the tables, see the SQL dump of the tables at `documentation/tables.sql` .
**MAILER**
The code related to the mail system can be found in the file `core/mailer.js`.
For the mailer to work the smtp credentials need to be changed in this file as well.
Then the mailer will work and use the mail templates from `mails/entry/`
SMTP can be configured with the following environment variables:
| Variable | Description |
|--------------|-------------------------------|
| `MAIL_HOST` | Host address for the mailer |
| `MAIL_PORT` | Port number for the mailer |
| `MAIL_USER` | Mailer User |
| `MAIL_PASS` | Mailer Password |
To debug and preview the emails, we use [MailHog](https://github.com/mailhog/MailHog).
When installing the Human Connection Clock without Docker, you have to install MailHog manually (see link for details).
Then set the host address of MailHog in the Human Connection Clock API and use `1025` as the port number.
Assuming MailHog is running on localhost or you have chosen the Docker installation, you can debug and preview the mails under [http://localhost:8025/](http://localhost:8025/).
## Installation
**PREREQUESITES**
Before starting the installation you need to make sure you have a recent version of [Git](https://git-scm.com/), [Nodejs](https://nodejs.org/en/) and [Npm](https://www.npmjs.com/get-npm) installed.
E.g. we have the following versions:
```
$ git --version
git version 2.14.2.windows.1
$ node --version
v10.15.0
$ npm --version
4.6.0
Git: 2.14.2
Node: 10.15.0
Npm: 4.6.0
OS: Windows 10
```
**DOCKER INSTALLATION**
The Human Connection Clock API server comes bundled as a Docker Container, which enables you to run then server out of the box.
Of course you need to have a recent version of [Docker](https://www.docker.com/get-started) installed. If you don't have Docker, follow the instructions of the link.
You can check the version like this:
```
$ docker -v
Docker version 18.09.1, build 4c52b90
```
To run the Docker version, follow these steps:
1. First you need to clone the git repository of the Human Connection Clock API. Head to a directory where you want the git repository to reside
and open the directory in the console. Then run `git clone https://github.com/Human-Connection/Human-Connection-Clock-API.git` to clone the repository to this directory.
2. Go to the newly created Human-Connection-Clock-API directory (`cd Human-Connection-Clock-API` in the console)
3. Run `docker-compose up`. This will build the Docker container on first startup and run it. This can take a while, but after some time you should see the Human Connection Clock ticking.
4. To create an initial API key and sample entries, run `docker-compose exec db_api seed.sh`. The initial API key you can use with your requests will have the value `secret`.
Now the Human Connection Clock API server is ready for usage at [http://127.0.0.1:1337](http://127.0.0.1:1337)
**LOCAL INSTALLATION & USAGE**
If you do not want to use the docker version, you can also install the Human Connection Clock API server locally.
1. First you need to clone the git repository of the Human Connection Clock API. Head to a directory where you want the git repository to reside
and open the directory in the console. Then run `git clone https://github.com/Human-Connection/Human-Connection-Clock-API.git` to clone the repository to this directory.
2. Go to the newly created Human-Connection-Clock-API directory (`cd Human-Connection-Clock-API` in the console) and run `npm install`.
Now all the dependencies should install.
3. Edit the file `core/db.js` and add your MySQL credentials (host, user, password, database name).
4. Create the tables - TODO: Add create table script & insert start values
5. Edit the file `core/mailer.js` and add your smtp credentials (host, user, password)
Now the Human Connection Clock API server is ready to tick.
## Usage
**START THE SERVER**
This section only applies if you have chosen the local installation.
When installing the Human Connection Clock API server with Docker, the server is starting automatically.
In the base Human-Connection-Clock-API directory run
`npm run start`
in the console to start the Human Connection Clock API server.
This will start Nodemon and the Node.js server, which will start listening for and processing requests at [http://localhost:1337](http://localhost:1337).
**RUN DATABASE MIGRATIONS**
This section only applies if you have chosen the local installation.
When installing the Human Connection Clock API server with Docker, the database migrations are applied automatically.
To create the necessary tables by applying the database migrations, run `db-migrate up` in the console.
This should give you an output like this:
```
$ db-migrate up
[INFO] Processed migration 20190206134449-entries
[INFO] Processed migration 20190206140226-apikeys
[INFO] Done
```
**MAKE REQUESTS**
Pro Tip: Get [Postman](https://www.getpostman.com/) to make requests. This amazing tool makes working with APIs way easier.
When using the default port 1337 (which you do if you haven't changed it in server.js), you can send requests to the Human Connection Clock API to `http://127.0.0.1:1337`.
Refer to the list of routes below, to see all possible requests with description you can make.
**ROUTES**
List of routes / endpoints
| Method | URI | Description |
|---|---|---|
| GET | http://127.0.0.1/cube.php | - Temp Route until path can be changed
- Returns the current number of confirmed entries
- No authentication required
- Returns a number/string (we change to json once we can adjust hardware clocks) |
| GET | http://127.0.0.1/entries/verify/:k | - Verify an entry with a email validation link/hash :k (for example http://127.0.0.1/entries/verify/sadSdjsarj3jf3j3wfmwfj3w)
- Returns Json {success : true || false, invalidKeyError if hash is invalid/used} |
| POST | http://127.0.0.1/entries | - Requires auth (see AUTHENTICATION)
- Create a new entry from body parameters
- Body parameters: firstname, lastname, email, country, message, anon (int 0 or 1), image
- Returns Json {success : true}
- May return errors mimeError, sizeError, missingFields, fieldErrors, missingImageError |
| GET | http://127.0.0.1/entries | - Requires auth
- Get back all entries
- Parameters: limit (default 10), offset (default 0) and active (default false)
- If active is true, only confirmed and active accounts will be returned
- Returns Json {success : true, results : out, totalCount : results.length, page : offset} or
- Return {success : false, message : "error"}|
**AUTHENTICATION**
To authenticate simply send parameter "API-Key" and the API key as the value with each request in the header
```
_____
_.'_____`._
.'.-' 12 `-.`.
/,' 11 1 `.\
// 10 2 \\
;; ::
|| 9 ---O----- 3 ||
:: ;;
\ 8 4 //
\`. 7 5 ,'/
'.`-. __6__ .-'.'
((-._____.-))
_)) ((_
'--' COC '--'
```