time-tracking-api

README

Time Tracking API

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.

Setup

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

Option #1: Docker

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.

Option #2: Local

Database

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

Run Server

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

Testing

Unit Tests

Unit tests can be run using:

make unit_test

Integration Tests

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

make int_test

Postman Tests

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

API

Authentication Token

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

Authentication

Method	Path	Request	Response	Notes
POST	/api/auth/login	LoginRequest	AuthResponse	Does not require an authentication token
POST	/api/auth/token		AuthResponse
POST	/api/auth/logout		{}
POST	/api/auth/forgot	EmailRequest	{}	Does not require an authentication token. Sends a forgot password validation email.

Profile

Method	Path	Request	Response	Notes
GET	/api/profile/		ProfileResponse
PUT	/api/profile/	ProfileRequest	ProfileResponse
PUT	/api/profile/password	PasswordChangeRequest	{}

Account

Method	Path	Request	Response	Notes
POST	/api/account	AccountRequest	ProfileResponse	Does not require an authentication token
PUT	/api/account	AccountUpdateRequest	ProfileResponse
GET	/api/account		AccountResponse
GET	/api/account/users		[]ProfileResponse
POST	/api/account/user	AddUserRequest	ProfileResponse

Client

Method	Path	Request	Response	Notes
GET	/api/client/{client_id}	string	ClientResponse
GET	/api/client/all		[]ClientResponse
GET	/api/client/archived		[]ClientResponse
POST	/api/client/	ClientRequest	ClientResponse
PUT	/api/client/	ClientRequest	{}
DELETE	/api/client/	ClientRequest	{}
PUT	/api/client/archive	ClientRequest	{}
PUT	/api/client/restore	ClientRequest	{}

Project

Method	Path	Request	Response	Notes
GET	/api/project/{project_id}	string	ProjectResponse
GET	/api/project/all		[]ProjectResponse
GET	/api/project/archived		[]ProjectResponse
POST	/api/project/	ProjectContainerRequest	ProjectResponse
PUT	/api/project/	ProjectContainerRequest	{}
DELETE	/api/project/	ProjectIdRequest	{}
PUT	/api/project/archive	ProjectIdRequest	{}
PUT	/api/project/restore	ProjectIdRequest	{}
POST	/api/project/copy/last/week	StartAndEndDateRequest	{} or TimeRangeResponse	Empty if no records the prior week

Time

Method	Path	Request	Response	Notes
GET	/api/time/week		TimeRangeResponse
GET	/api/time/week/{startDate}	string	TimeRangeResponse	Date must be in the ISOShortDateFormat (e.g. "2006-01-02")
PUT	/api/time/	TimeEntryRangeRequest	{}
POST	/api/time/project/week	ProjectWeekRequest	{}
DELETE	/api/time/project/week	ProjectDeleteRequest	{}

Task

Method	Path	Request	Response	Notes
GET	/api/task/{taskId}	string	TaskResponse
GET	/api/task/all		[]TaskResponse
GET	/api/task/archived		[]TaskResponse
POST	/api/task/	TaskRequest	TaskResponse
PUT	/api/task/	TaskRequest	{}
PUT	/api/task/archive	TaskRequest	{}
PUT	/api/task/restore	TaskRequest	{}
DELETE	/api/task/	TaskRequest	{}

Report

Method	Path	Request	Response	Notes
GET	/api/report/time/client	query parameters: from, to, page	[]ClientReportResponse	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/project	query parameters: from, to, page	[]ProjectReportResponse	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/task	query parameters: from, to, page	[]TaskReportResponse	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/person	query parameters: from, to, page	[]PersonReportResponse	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/export/client	query parameters: from, to	CSV file with content type text/csv	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/export/project	query parameters: from, to	CSV file with content type text/csv	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/export/task	query parameters: from, to	CSV file with content type text/csv	from and to are date strings in the ISOShortDateFormat format
GET	/api/report/time/export/person	query parameters: from, to	CSV file with content type text/csv	from and to are date strings in the ISOShortDateFormat format

Ping

Method	Path	Request	Response	Notes
GET	/_ping		Text ok with content type text/plain

Errors

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

Status Code	Error
400	http.StatusBadRequest
401	http.StatusUnauthorized
404	http.StatusNotFound
405	http.StatusMethodNotAllowed
500	http.StatusInternalServerError

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" }
}