API for online timekeeping: REST interface

(Technical specification for software developers)

The online timekeeping provides a simple REST interface for software developers to create time entries. The interface is implemented as a REST service and is also suitable for connecting time clocks.

Requirements:

The REST API must be activated in the settings of the online time recording system (tab 'Security') and a password must be set. Note: The same password is also used for the web service interface.

Technical description

A testing resource is available at: https://www.goodtimetracking.com/goodtime-rs/api/hello/sayhello

A test resource for the login is available at: https://www.goodtimetracking.com/goodtime-rs/api/hello/securedSayhello For this call, https://www.goodtimetracking.com/goodtime-rs/goodtime-rs/api/login must be called beforehand.

A simple test client in Java for all available functions as a zip file or tar file.

Description of resources

Ressource @GET /api/hello/sayhello

This resource for testing returns a hello.

Parameter:
none
Return value:
String
'Hello!'

Ressource @GET /api/hello/securedSayhello

This resource can be used to test the login. The login must be called beforehand.

Parameter:
none
Return value:
String
'Secured Hello!'

Method @POST /api/login

This resource can be used for login.

Parameter:
{loginemail, apipassword}
The login email of the admin is used as the login email. The API-password is set in the settings (tab 'Security'). Example: {"loginemail": "admin@gtdemo.en", "apipassword": "12345678"}
Return value:
JSON web token
The returned token must be sent as a header with every request for authentication.

Method @GET /api/time/timecategories

This resource returns a list of all time types.

Parameter:
none
Return value:
[{id, name}, ...]
List of time types in the format: time type id, time type name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "working hours"}, ...]

Method @GET /api/time/users

This resource returns a list of all users' login emails.

Parameter:
none
Return value:
[{loginemail}, ...]
The list of login emails of all users. Example: [{"admin@gtdemo.en"}, ...]

Method @GET /api/time/projects

This resource returns the list of projects.

Parameter:
none
Return value:
[{id, name}, ...]
The list of projects in the format: project id, project name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demo Project"}, ...]

Method @GET /api/time/projects/{useremail}

This resource returns a list of projects for a specific user.

Parameter:
{useremail}
The login email of the user in question. Example: @GET /projects/maier@gtdemo.en
Return value:
[{id, name}, ...]
The list of projects in the format: project id, project name. Example: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demo Project"}, ...]

Method @POST api/time/createtimeentry

With this resource you can create a new time entry.

Parameter:
{starttime, endtime, useremail, timetypeid, projectid}
starttime and endtime must be specified in the following format: YYYY-DD-MMTHH:MM:00 - e.g.: '2007-23-03T10:15:00'. Specifying a projectid is optional.

Example of a time entry:
{"starttime": "2007-23-03T10:15:00", "endtime": "2007-23-03T18:21:00", "useremail": "maier@gtdemo.de", "timetypeid": "83be5360-6067-4a09-a970-1ff2413d7101", "projectid": "2aeba501-ca09-41b2-a938-654d178914e4"}
Return value:
none