{"id":20768004,"url":"https://github.com/human-connection/human-connection-clock-api","last_synced_at":"2025-06-30T11:03:16.729Z","repository":{"id":48274027,"uuid":"149597954","full_name":"Human-Connection/Human-Connection-Clock-API","owner":"Human-Connection","description":"Nodejs api for Human Connection Clock","archived":false,"fork":false,"pushed_at":"2021-08-03T19:03:35.000Z","size":1188,"stargazers_count":4,"open_issues_count":21,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-30T11:03:14.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"EJS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Human-Connection.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-20T11:21:28.000Z","updated_at":"2022-11-27T03:56:36.000Z","dependencies_parsed_at":"2022-09-09T09:51:32.875Z","dependency_job_id":null,"html_url":"https://github.com/Human-Connection/Human-Connection-Clock-API","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Human-Connection/Human-Connection-Clock-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Human-Connection%2FHuman-Connection-Clock-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Human-Connection%2FHuman-Connection-Clock-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Human-Connection%2FHuman-Connection-Clock-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Human-Connection%2FHuman-Connection-Clock-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Human-Connection","download_url":"https://codeload.github.com/Human-Connection/Human-Connection-Clock-API/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Human-Connection%2FHuman-Connection-Clock-API/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262762436,"owners_count":23360326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T11:34:26.072Z","updated_at":"2025-06-30T11:03:16.686Z","avatar_url":"https://github.com/Human-Connection.png","language":"EJS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Human Connection Clock - API Server (Backend)\n\n\nThis repository contains the API Server - or in other terms Backend - of the Human Connection Clock.\n\nTo find out more about the Human Connection Clock and Human Connection - the network behind it - visit https://human-connection.org/en/.\n\n## Tech Stack\n\n* Node.js: The API Server is running on [Node.js](https://nodejs.org/en/) - a JavaScript runtime environment for server-side scripting\n* Express.js: We use the [Express.js](https://expressjs.com/en/) framework - a Node.js framework to help build web applications\n* Nodemon: We use [Nodemon](https://nodemon.io/) for development - a handy replacement wrapper for Node.js that automatically restarts the application on file changes\n* MySQL: We use [MySQL](https://www.mysql.com) as our relational database of choice to store our data \n* MailHog: We use [MailHog](https://github.com/mailhog/MailHog) to debug and preview the email communication\n\n## Project Structure \u0026 Components\n\n**PROJECT STRUCTURE / DIRECTORIES**\n\n* server.js: The starting point for this Node.js application which starts the server\n* core/: The core directory contains the most important files of the project like database, mailer, router and main controller\n* core/entryController.js: Is the main controller for all the requests\n* core/restapi.js: All routes can be found here, they will also be listed further down\n* documentation/: Documentation for the Human Connection Clock API\n* mails/: The mails directory holds the mail templates\n* migrations/: Migrations for the database\n* public/: The public directory is not used for now\n\n\n**DATABASE**\n\nWe use MySQL for the COC API as our relational database. \nCurrently all of the database related code can be found in the `core/db.js` file.\nThis includes the credentials for the database (host, user, password and db name) and can be changed in this file.\n\nMySQL DB can be configured with the following environment variables:\n\n| Variable     | Description                   |\n|--------------|-------------------------------|\n| `MYSQL_HOST` | Host address for the database |\n| `MYSQL_DB`   | Database Name                 |\n| `MYSQL_USER` | MySQL User                    |\n| `MYSQL_PASS` | MySQL Password                |\n\nCurrently we have two tables:\n* apikeys: Contains the apikeys required to perform authorized API request\n* entries: Stores the user entries for the Human Connection Clock\n\nFor more information about the tables, see the SQL dump of the tables at `documentation/tables.sql` .\n\n**MAILER**\n\nThe code related to the mail system can be found in the file `core/mailer.js`.\nFor the mailer to work the smtp credentials need to be changed in this file as well.\nThen the mailer will work and use the mail templates from `mails/entry/`\n\nSMTP can be configured with the following environment variables:\n\n| Variable     | Description                   |\n|--------------|-------------------------------|\n| `MAIL_HOST`  | Host address for the mailer   |\n| `MAIL_PORT`  | Port number for the mailer    |\n| `MAIL_USER`  | Mailer User                   |\n| `MAIL_PASS`  | Mailer Password               |\n\n\n\nTo debug and preview the emails, we use [MailHog](https://github.com/mailhog/MailHog). \nWhen installing the Human Connection Clock without Docker, you have to install MailHog manually (see link for details).\nThen set the host address of MailHog in the Human Connection Clock API and use `1025` as the port number.\n\nAssuming 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/).\n\n## Installation\n\n**PREREQUESITES**\n\nBefore 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. \nE.g. we have the following versions:\n```\n$ git --version\ngit version 2.14.2.windows.1\n$ node --version\nv10.15.0\n$ npm --version\n4.6.0\n\nGit: 2.14.2\nNode: 10.15.0\nNpm: 4.6.0\nOS: Windows 10\n```\n\n**DOCKER INSTALLATION**\n\nThe Human Connection Clock API server comes bundled as a Docker Container, which enables you to run then server out of the box.\n\nOf 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.\nYou can check the version like this:\n```\n$ docker -v\nDocker version 18.09.1, build 4c52b90\n``` \n\nTo run the Docker version, follow these steps:\n1. 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\nand 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.\n2. Go to the newly created Human-Connection-Clock-API directory (`cd Human-Connection-Clock-API` in the console)\n3. 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.\n4. 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`.\n\nNow the Human Connection Clock API server is ready for usage at [http://127.0.0.1:1337](http://127.0.0.1:1337)\n\n**LOCAL INSTALLATION \u0026 USAGE**\n\nIf you do not want to use the docker version, you can also install the Human Connection Clock API server locally.\n\n1. 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\nand 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.\n2. Go to the newly created Human-Connection-Clock-API directory (`cd Human-Connection-Clock-API` in the console) and run `npm install`.\nNow all the dependencies should install.\n3. Edit the file `core/db.js` and add your MySQL credentials (host, user, password, database name). \n4. Create the tables - TODO: Add create table script \u0026 insert start values\n5. Edit the file `core/mailer.js` and add your smtp credentials (host, user, password)\n\nNow the Human Connection Clock API server is ready to tick.\n\n## Usage\n\n**START THE SERVER**\n\nThis section only applies if you have chosen the local installation. \nWhen installing the Human Connection Clock API server with Docker, the server is starting automatically.\n\nIn the base Human-Connection-Clock-API directory run\n\n`npm run start`\n\nin the console to start the Human Connection Clock API server.\nThis will start Nodemon and the Node.js server, which will start listening for and processing requests at [http://localhost:1337](http://localhost:1337).\n\n**RUN DATABASE MIGRATIONS**\n\nThis section only applies if you have chosen the local installation. \nWhen installing the Human Connection Clock API server with Docker, the database migrations are applied automatically.\n\nTo create the necessary tables by applying the database migrations, run `db-migrate up` in the console. \n\nThis should give you an output like this:\n```\n$ db-migrate up\n[INFO] Processed migration 20190206134449-entries\n[INFO] Processed migration 20190206140226-apikeys\n[INFO] Done\n```\n\n**MAKE REQUESTS**\n\nPro Tip: Get [Postman](https://www.getpostman.com/) to make requests. This amazing tool makes working with APIs way easier.\n\nWhen 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`.\n\nRefer to the list of routes below, to see all possible requests with description you can make.\n\n**ROUTES**\n\nList of routes / endpoints\n\n| Method | URI | Description |\n|---|---|---|\n| GET | http://127.0.0.1/cube.php | - Temp Route until path can be changed\u003cbr/\u003e- Returns the current number of confirmed entries\u003cbr/\u003e- No authentication required\u003cbr/\u003e- Returns a number/string (we change to json once we can adjust hardware clocks)  |\n| 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)\u003cbr/\u003e- Returns Json {success : true || false, invalidKeyError if hash is invalid/used} |\n| POST | http://127.0.0.1/entries | - Requires auth (see AUTHENTICATION)\u003cbr/\u003e- Create a new entry from body parameters\u003cbr/\u003e- Body parameters: firstname, lastname, email, country, message, anon (int 0 or 1), image\u003cbr/\u003e- Returns Json {success : true}\u003cbr/\u003e- May return errors mimeError, sizeError, missingFields, fieldErrors, missingImageError |\n| GET | http://127.0.0.1/entries  | - Requires auth\u003cbr/\u003e- Get back all entries\u003cbr/\u003e- Parameters: limit (default 10), offset (default 0) and active (default false)\u003cbr/\u003e- If active is true,  only confirmed and active accounts will be returned\u003cbr/\u003e- Returns Json {success : true, results : out, totalCount : results.length, page : offset} or\u003cbr/\u003e - Return {success : false, message : \"error\"}|\n\n**AUTHENTICATION**\n\nTo authenticate simply send parameter \"API-Key\" and the API key as the value with each request in the header\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n```\n       _____\n    _.'_____`._\n  .'.-'  12 `-.`.\n /,' 11      1 `.\\\n// 10           2 \\\\\n;;                 ::\n|| 9  ---O-----  3 ||\n::                 ;;\n\\ 8            4  //\n \\`. 7       5 ,'/\n '.`-. __6__ .-'.'\n   ((-._____.-))\n   _))       ((_\n  '--'  COC  '--'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuman-connection%2Fhuman-connection-clock-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuman-connection%2Fhuman-connection-clock-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuman-connection%2Fhuman-connection-clock-api/lists"}