Go API for tracking time.

Manage time entries for tasks that are associated with projects. Built with Golang and PostgreSQL.

See the React Time Tracking App for a reference UI.

You can use Docker to get started quickly or run the Go server locally using a PostgreSQL instance.

To run the Go server and PostgreSQL database in a container you can start both using Docker Compose:

docker-compose up

The API will be available at http://localhost:8000 and the PostgreSQL instance will be exposed on port 5432.

Ensure you have PostgreSQL 12 or higher installed and running.

Create a timetracker database and role using the bootstrap SQL in:

./database/bootstrap.sql

Then create the schema in the timetracker database using:

./database/schema-1.sql

To run the Go API server use the run Makefile target:

make run

which will start the server on the port configured in config/dev.yml. By default the API will be available at http://localhost:8000

Unit tests can be run using:

make unit_test

Integration tests are managed under the integration_test root folder and can be run using:

make int_test

Additional functional tests are available using the Postman tool. These tests require the newman Postman command-line runner. Install using:

npm install -g newman

The test rely on the database/bootstrap.sql data to be present. To run the Postman tests locally, first start the web server:

make run

then run the Postman tests:

make postman

Most of the REST endpoints require an authentication token which can be supplied as a custom header:

Authorization: Bearer {token}

Endpoints that do not require a token are noted below.

To validate the local or Docker instance is working you can hit the /_ping endpoint and you should get back an OK response:

curl http://localhost:8000/_ping

If an API fails, the HTTP status code will reflect the type of error response. Common error status codes are:

Errors will produce a JSON response that contains a status field set to error. Error details will be included as part of the serialized Error struct.

For example the error response below shows the JSON response for a 400 error when an email value is invalid:

{
  "status": "error",
  "error": "invalid input",
  "message": "Invalid email",
  "code": "InvalidEmail",
  "detail": {"field": "email" }
}