Home

API endpoints

Table of contents

1. Authentication

   1. Sign in
   2. Sign out

2. Employee report

   1. Show report

3. Admin

4. Users

   1. List users
   2. Show user
   3. Create user
   4. Update user
   5. Delete user

5. Work days

   1. List work days
   2. Show work day
   3. Create work day
   4. Update work day
   5. Delete work day

6. Reports

   1. Show report
   2. Create report
   3. Update report
   4. Delete report

7. Errors

   1. Unauthorized
   2. Forbidden
   3. Not found
   4. Unprocessable entity
   5. Server error

Authentication

Authentication is implemented using JWTs. When a user enters their credentials, a token is sent back to them, and it's the user's (client) responsibility to include it inside the Authorization header on subsequent requests. This token will be referenced as jwt_token from now on.

Sign in

Authenticates user with provided credentials.

Request

POST /users/sign_in

Headers

• Accept: application/json
• Content-Type: application/json

Parameters

Body parameters

Name	Type	Description
user	object	required An object containing the sign in credentials. Keys and values of this object are described below
email	string	required Email of the user. It should be included inside the user object
password	string	required Password of the user. It should be included inside the user object

Body

{"user": { "email": "[email protected]", "password": "some-password" } }

Response

Status code

200

Response body

{
	"id": 1,
	"email": "[email protected]",
	"created_at": "2019-11-15T20:04:53.321Z",
	"updated_at": "2019-11-15T20:04:53.321Z",
	"name": "User name",
	"position": "Some position or null",
	"role": "some-role"
}

---

Sign out

Leaves the user unauthenticated.

Request

DELETE /users/sign_out

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Response

Status code

204

Employee report

Show report

Fetches report corresponding to the authenticated user. If no report exists, worked days for the last month are returned.

Request

GET /users/report

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Response

Status code

200

Response body

[
	{
		"id": 1,
		"day": "2019-10-14",
		"arrived_at": "2019-10-14T09:56:00.000Z",
		"left_at": "2019-10-14T17:48:00.000Z"
	},
	{
		"id": 2,
		"day": "2019-10-15",
		"arrived_at": "2019-10-15T09:56:00.000Z",
		"left_at": "2019-10-15T17:48:00.000Z"
	},
	...
]

Admin

The following endpoints are accesible only by administrator users. This is accomplished using the role associated to a user.

Users

The following endpoints allow to manage users inside the platform.

List users

Fetches list of all users.

Request

GET /admin/users

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Response

Status code

200

Response body

[
	{
		"id": 1,
		"email": "[email protected]",
		"name": "User name 1",
		"position": "Some position or null",
		"role": "some-role",
		"created_at": "2019-11-15T20:04:53.321Z",
		"updated_at": "2019-11-15T20:04:53.321Z",
		"url": "http://localhost:3000/admin/users/1"
	},
	{
		"id": 2,
		"email": "[email protected]",
		"name": "User name 2",
		"position": "Some position or null",
		"role": "some-role",
		"created_at": "2019-11-15T20:04:53.321Z",
		"updated_at": "2019-11-15T20:04:53.321Z",
		"url": "http://localhost:3000/admin/users/2"
	},
	...
]

---

Show user

Fetches a particular user.

Request

GET /admin/users/:id

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
id	number	A number representing the id of the user

Response

Status code

200

Response body

{
	"id": 1,
	"email": "[email protected]",
	"name": "User name 1",
	"position": "Some position or null",
	"role": "some-role",
	"created_at": "2019-11-15T20:04:53.321Z",
	"updated_at": "2019-11-15T20:04:53.321Z",
	"url": "http://localhost:3000/admin/users/1"
}

---

Create user

Creates a new user.

Request

POST /admin/users

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

Body parameters

Name	Type	Description
user	object	required An object containing the new user data. Keys and values of this object are described below
email	string	required Email of the user. It should be included inside the user object
password	string	required Password of the user. It should be included inside the user object
name	string	required Name of the user. It should be included inside the user object
position	string	Position associated to the user. It should be included inside the user object
role	string	Role of the user. It has two possible values: "employee" or "admin". Defaults to "employee". It should be included inside the user object

Body

{"user": { "email": "[email protected]", "password": "some-password", "name": "Some name", "position": "Some position", "role": "some-role" } }

Response

Status code

201

Response body

{
	"id": 2,
	"email": "[email protected]",
	"name": "Some name",
	"position": "Some position",
	"role": "some-role",
	"created_at": "2019-11-15T20:04:53.321Z",
	"updated_at": "2019-11-15T20:04:53.321Z",
	"url": "http://localhost:3000/admin/users/2"
}

---

Update user

Updates an existing user.

Request

PATCH /admin/users/:id

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
id	number	A number representing the id of the user

Body parameters

Name	Type	Description
user	object	required An object containing the user data that needs to be updated. Keys and values of this object are described below
email	string	Email of the user. It should be included inside the user object
password	string	Password of the user. It should be included inside the user object
name	string	Name of the user. It should be included inside the user object
position	string	Position associated to the user. It should be included inside the user object
role	string	Role of the user. It has two possible values: "employee" or "admin". Defaults to "employee". It should be included inside the user object

Body

{"user": { "email": "[email protected]" } }

Note: Parameters omitted inside the body will be ignored when updating the user.

Response

Status code

200

Response body

{
	"id": 2,
	"email": "[email protected]",
	"name": "Some name",
	"position": "Some position",
	"role": "some-role",
	"created_at": "2019-11-15T20:04:53.321Z",
	"updated_at": "2019-11-15T20:04:53.321Z",
	"url": "http://localhost:3000/admin/users/2"
}

---

Delete user

Deletes an existing user.

Request

DELETE /admin/users/:id

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
id	number	A number representing the id of the user

Response

Status code

204

Work days

Work days are in charge of specifying the date and times of a worked day for an employee. Therefore, these work days are always associated to a user. For that reason, each of the following endpoints include the user inside the URL.

List work days

Fetches list of work days for a user.

Request

GET /admin/users/:user_id/work_days

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Response

Status code

200

Response body

[
	{
		"id": 32,
		"day": "2019-10-14",
		"arrived_at": "2019-10-14T09:56:00.000Z",
		"left_at": "2019-10-14T17:48:00.000Z",
		"created_at": "2019-10-15T17:48:00.000Z",
		"updated_at": "2019-10-15T17:48:00.000Z",
		"url": "http://localhost:3000/admin/users/2/work_days/32",
		"human_url": "http://localhost:3000/admin/users/2/work_days/2019-10-14"
	},
	{
		"id": 33,
		"day": "2019-10-15",
		"arrived_at": "2019-10-15T09:56:00.000Z",
		"left_at": "2019-10-15T17:48:00.000Z",
		"created_at": "2019-10-15T17:48:00.000Z",
		"updated_at": "2019-10-15T17:48:00.000Z",
		"url": "http://localhost:3000/admin/users/2/work_days/33",
		"human_url": "http://localhost:3000/admin/users/2/work_days/2019-10-15"
	},
	...
]

---

Show work day

Fetches a particular work day for a user.

Request

GET /admin/users/:user_id/work_days/:id_or_day

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user
id_or_day	string	A number representing the id of the user or a string with the day in YYYY-MM-DD format

Response

Status code

200

Response body

{
	"id": 33,
	"day": "2019-10-15",
	"arrived_at": "2019-10-15T09:56:00.000Z",
	"left_at": "2019-10-15T17:48:00.000Z",
	"created_at": "2019-10-15T17:48:00.000Z",
	"updated_at": "2019-10-15T17:48:00.000Z",
	"url": "http://localhost:3000/admin/users/2/work_days/33",
	"human_url": "http://localhost:3000/admin/users/2/work_days/2019-10-15"
}

---

Create work day

Creates a new work day for a user.

Request

POST /admin/users/:user_id/work_days

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Body parameters

Name	Type	Description
work_day	object	required An object containing the new work day data. Keys and values of this object are described below
day	string	required The day in YYYY-MM-DD format. It should be included inside the work_day object
arrived_at	string	The datetime of the arrival of the employee, in YYYY-MM-DD HH:mm:ss format. It should be included inside the work_day object
left_at	string	The datetime when the employee left, in YYYY-MM-DD HH:mm:ss format. It should be included inside the work_day object

Body

{"work_day": { "day": "2019-11-16", "arrived_at": "2019-11-16 09:00:05", "left_at": "2019-11-16 18:58:23" } }

Response

Status code

201

Response body

{
	"id": 66,
	"day": "2019-11-16",
	"arrived_at": "2019-11-16T09:00:05.000Z",
	"left_at": "2019-11-16T18:58:23.000Z",
	"created_at": "2019-11-16T00:32:11.990Z",
	"updated_at": "2019-11-16T00:32:11.990Z",
	"url": "http://localhost:3000/admin/users/2/work_days/66",
	"human_url": "http://localhost:3000/admin/users/2/work_days/2019-11-16"
}

---

Update work day

Updates an existing work day for a user.

Request

PATCH /admin/users/:user_id/work_days/:id_or_day

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user
id_or_day	string	A number representing the id of the user or a string with the day in YYYY-MM-DD format

Body parameters

Name	Type	Description
work_day	object	required An object containing the work day data that needs to be updated. Keys and values of this object are described below
day	string	The day in YYYY-MM-DD format. It should be included inside the work_day object
arrived_at	string	The datetime of the arrival of the employee, in YYYY-MM-DD HH:mm:ss format. It should be included inside the work_day object
left_at	string	The datetime when the employee left, in YYYY-MM-DD HH:mm:ss format. It should be included inside the work_day object

Body

{"work_day": { "left_at": "2019-11-06 17:30:00" } }

Note: Parameters omitted inside the body will be ignored when updating the work day.

Response

Status code

200

Response body

{
	"id": 66,
	"day": "2019-11-16",
	"arrived_at": "2019-11-16T09:00:05.000Z",
	"left_at": "2019-11-16T17:30:00.000Z",
	"created_at": "2019-11-16T00:32:11.990Z",
	"updated_at": "2019-11-16T00:32:11.990Z",
	"url": "http://localhost:3000/admin/users/2/work_days/66",
	"human_url": "http://localhost:3000/admin/users/2/work_days/2019-11-16"
}

---

Delete work day

Deletes an existing work day of a user.

Request

DELETE /admin/users/:user_id/work_days/:id_or_day

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user
id_or_day	string	A number representing the id of the user or a string with the day in YYYY-MM-DD format

Response

Status code

204

Reports

A report is always associated to a user. For that reason, each of the following endpoints include the user inside the URL.

Show report

Fetches the report associated to a user. It includes the work days in the range of dates specified by the report. If no report exists, worked days for the last month are returned.

Request

GET /admin/users/:user_id/report

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Response

Status code

200

Response body

{
	"id": 1,
	"start_date": "2019-10-01",
	"end_date": "2019-10-20",
	"created_at": "2019-11-15T20:04:53.387Z",
	"updated_at": "2019-11-15T20:04:53.387Z",
	"url": "http://localhost:3000/admin/users/2/report",
	"work_days": [
		{
			"id": 32,
			"day": "2019-10-14",
			"arrived_at": "2019-10-14T09:56:00.000Z",
			"left_at": "2019-10-14T17:48:00.000Z",
			"created_at": "2019-10-15T17:48:00.000Z",
			"updated_at": "2019-10-15T17:48:00.000Z",
			"url": "http://localhost:3000/admin/users/2/work_days/32",
			"human_url": "http://localhost:3000/admin/users/2/work_days/2019-10-14"
		},
		{
			"id": 33,
			"day": "2019-10-15",
			"arrived_at": "2019-10-15T09:56:00.000Z",
			"left_at": "2019-10-15T17:48:00.000Z",
			"created_at": "2019-10-15T17:48:00.000Z",
			"updated_at": "2019-10-15T17:48:00.000Z",
			"url": "http://localhost:3000/admin/users/2/work_days/33",
			"human_url": "http://localhost:3000/admin/users/2/work_days/2019-10-15"
		},
		...
	]
}

---

Create report

Creates a new report for a user. It there was a report previously created, it returns that report (does not replace it).

Request

POST /admin/users/:user_id/report

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Body parameters

Name	Type	Description
report	object	required An object containing the new report data. Keys and values of this object are described below
start_date	string	required The start date in YYYY-MM-DD format. It should be included inside the report object
end_date	string	required The end date in YYYY-MM-DD format. It should be included inside the report object

Body

{"report": { "start_date": "2019-11-12", "end_date": "2019-11-14" } }

Response

Status code

201

Response body

{
	"id": 2,
	"start_date": "2019-11-12",
	"end_date": "2019-11-14",
	"created_at": "2019-11-15T20:04:53.387Z",
	"updated_at": "2019-11-15T20:04:53.387Z",
	"url": "http://localhost:3000/admin/users/2/report",
	"work_days": [
		{
			"id": 52,
			"day": "2019-11-12",
			"arrived_at": "2019-11-12T09:56:00.000Z",
			"left_at": "2019-11-12T17:48:00.000Z",
			"created_at": "2019-10-15T17:48:00.000Z",
			"updated_at": "2019-10-15T17:48:00.000Z",
			"url": "http://localhost:3000/admin/users/2/work_days/52",
			"human_url": "http://localhost:3000/admin/users/2/work_days/2019-11-12"
		},
		{
			"id": 53,
			"day": "2019-11-13",
			"arrived_at": "2019-11-13T09:56:00.000Z",
			"left_at": "2019-11-13T17:48:00.000Z",
			"created_at": "2019-10-15T17:48:00.000Z",
			"updated_at": "2019-10-15T17:48:00.000Z",
			"url": "http://localhost:3000/admin/users/2/work_days/53",
			"human_url": "http://localhost:3000/admin/users/2/work_days/2019-11-13"
		},
		...
	]
}

---

Update report

Updates an existing report associated to a user

Request

PATCH /admin/users/:user_id/report

Headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Body parameters

Name	Type	Description
report	object	required An object containing the report data that needs to be updated. Keys and values of this object are described below
start_date	string	The start date in YYYY-MM-DD format. It should be included inside the report object
end_date	string	The end date in YYYY-MM-DD format. It should be included inside the report object

Body

{"report": { "start_date": "2019-11-13" } }

Note: Parameters omitted inside the body will be ignored when updating the report.

Response

Status code

200

Response body

{
	"id": 2,
	"start_date": "2019-11-13",
	"end_date": "2019-11-14",
	"created_at": "2019-11-15T20:04:53.387Z",
	"updated_at": "2019-11-15T20:04:53.387Z",
	"url": "http://localhost:3000/admin/users/2/report",
	"work_days": [
		{
			"id": 53,
			"day": "2019-11-13",
			"arrived_at": "2019-11-13T09:56:00.000Z",
			"left_at": "2019-11-13T17:48:00.000Z",
			"created_at": "2019-10-15T17:48:00.000Z",
			"updated_at": "2019-10-15T17:48:00.000Z",
			"url": "http://localhost:3000/admin/users/2/work_days/53",
			"human_url": "http://localhost:3000/admin/users/2/work_days/2019-11-13"
		},
		...
	]
}

---

Delete report

Deletes an existing report associated to a user.

Request

DELETE /admin/users/:user_id/report

Headers

• Accept: application/json
• Authorization: Bearer jwt_token

Parameters

URL parameters

Name	Type	Description
user_id	number	A number representing the id of the user

Response

Status code

204

---

Errors

When something wrong happens with a request, an error object is returned. Depending on the type of error, the object can be one of three:

• Object with error key, string value with error details
• Object with errors key, array value containing elements with error details
• Object with generic keys, array values with error details

Note: Part of future work is to standardize errors.

The following categories of errors can occur:

Unauthorized

It happens when the user is not authenticated.

Status code

401

Response body

{
	"error": "You need to sign in before continuing."
}

---

Forbidden

It happens when the user is not authorized to request the resource.

Status code

403

Response body

{
	"errors": [
		{
			"status": 403,
			"title": "Forbidden",
			"message": "You are not authorized to access this resource."
		}
	]
}

---

Not found

It happens when the requested resource could not be found.

Status code

404

Response body

{
	"errors": [
		{
			"status": 404,
			"title": "Record not Found",
			"message": "We could not find the object you were looking for."
		}
	]
}

---

Unprocessable entity

It happens when there is data validation error.

Status code

422

Response body

{
	"some_field": [
		"is not valid data"
	]
}

---

Server error

Any error not covered by previous errors is considered a server error.

Status code

500

Response body

{
	"errors": [
		{
			"status": 500,
			"title": "Something went wrong",
			"message": "We encountered unexpected error"
		}
	]
}