Vacations API

General notes

Api for managing User's Vacations.

Content

Vacations collection:

[POST] create vacation
[GET] index, searching and filtering users

Single vacation:

[GET] vacation detail
[PUT/PATCH] update vacation
[DELETE] delete vacation

Vacations collection

Create vacation

POST /api/v0/vacations

To create new record this method needs permission create on vacations. To set is_approved, responder_id or approval_date user must be Admin or Manager.

Method for creating new vacation. After vacation is created, email for account activation is send to Admins and Managers.

Request

Param	Type	Description	Requirements
`vacation_from`	Date	Vacation's start date	Required. Must be a date prior to vacation_to.
`vacation_to`	Date	Vacation's end date	Required. Must be a date later than vacation_from.
`is_approved`	bool	Approval state	False as default. Vacation must be approved by Admin or Managers.
`note`	string	User's note	User can optionally add note to requested vacation.
`applicant_id`	int	Applicant's identification number	Gets id from request as default, but could be set by Admin or Manager.
`responder_id`	int	Responder's identification number	Gets id from request as default, but could be set by Admin or Manager.
`approval_date`	Date	Approval date	Gets date of current day as default, but could be set by Admin or Manager.

Vacation_from, Vacation_to and Applicant_id must be a unique combination.

Following parameters can only be set by Admin or Manager:

Param	Type	Description	Requirements
`is_approved`	bool	Approval state	False as default. Vacation must be approved by Admin or Managers.
`applicant_id`	int	Applicant's identification number	Gets id from request as default, but could be set by Admin or Manager.
`responder_id`	int	Responder's identification number	Gets id from request as default, but could be set by Admin or Manager.
`approval_date`	Date	Approval date	Gets date of current day as default, but could be set by Admin or Manager.

POST /api/v0/vacations HTTP/1.1
Content-Type: application/json

{
    "vacation_from": "2023-04-17",
    "vacation_to": "2023-04-24",
    "is_approved": false,
    "note": "Iure et saepe omnis nihil numquam repudiandae.",
    "applicant_id": 2,
}

Responses

201 CREATED

New Vacation was successfully created.

POST /api/v0/vacations HTTP/1.1
Content-Type: application/json
Status-Code: 201

{
    "id": 1,
    "vacation_from": "2022-04-17",
    "vacation_to": "2022-04-24",
    "days": 8,
    "is_approved": false,
    "note": "Iure et saepe omnis nihil numquam repudiandae.",
    "applicant_id": 2,
    "responder_id": null,
    "approval_date": null
}

422 UNPROCESSABLE ENTITY

Validation error occurred. Vacation start date is prior to vacation end date.

POST /api/v0/vacations HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "6c161767-f250-4adf-9925-9bc7e5057d57",
    "errors": [
        {
            "field": "vacation_to",
            "message": "datum musí být :vacation_from nebo pozdější."
        },
        {
            "field": "vacation_from",
            "message": "Datum musí být před nebo rovno :vacation_to."
        }
    ]
}

Vacations index

GET /api/v0/vacations

This method needs permission read on vacations.

Get list of existing Vacations.

Request

Index behaviour	Definition
Paginated by default	No
Sorting	`id`,`vacation_from`, `vacation_to`, `is_approved`, `applicant_id`, `responder_id`, `days`
Filters	`id`:enum, `vacation_from`:date , `vacation_to`:date, `is_approved`:bool, `applicant_id`:enum, `responder_id`:enum, `days`:enum

GET /api/v0/vacations HTTP/1.1

Responses

200 OK

GET /api/v0/vacations HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "items": [
        {
            "id": 2,
            "vacation_from": "2022-12-18",
            "vacation_to": "2022-12-28",
            "days": 11,
            "is_approved": false,
            "note": null,
            "applicant_id": 1,
            "responder_id": null,
            "approval_date": null
        },
        {
            "id": 3,
            "vacation_from": "2022-11-11",
            "vacation_to": "2022-11-14",
            "days": 4,
            "is_approved": false,
            "note": null,
            "applicant_id": 1,
            "responder_id": null,
            "approval_date": null
        }
    ]
}

Single vacation

Vacation detail

GET /api/v0/vacations/{vacation_id}

This method needs permission read on vacations.

Get Vacation detail.

Request

GET /api/v0/vacations/1 HTTP/1.1

Responses

200 OK

GET /api/v0/vacations/1 HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": 10,
    "vacation_from": "2022-12-28",
    "vacation_to": "2023-01-14",
    "days": 18,
    "is_approved": false,
    "note": null,
    "applicant_id": 2,
    "responder_id": null,
    "approval_date": null
}

404 NOT FOUND

Vacation was not found.

GET /api/v0/vacations/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "No query results for model.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

Update vacation

PUT/PATCH /api/v0/vacations/{vacation_id}

This method needs permission update on vacations.

Method for updating Vacation data.

Request

Param	Type	Description	Requirements
`vacation_from`	Date	Vacation's start date	Required. Must be a date prior to vacation_to.
`vacation_to`	Date	Vacation's end date	Required. Must be a date later than vacation_from.
`is_approved`	bool	Approval state	False as default. Vacation must be approved by Admin or Managers.
`note`	string	User's note	User can optionally add note to requested vacation.
`applicant_id`	int	Applicant's identification number	Gets id from request as default, but could be set by Admin or Manager.
`responder_id`	int	Responder's identification number	Gets id from request as default, but could be set by Admin or Manager.
`approval_date`	Date	Approval date	Gets date of current day as default, but could be set by Admin or Manager.

For PATCH method any field can be omitted.
Standard user cannot update fields if vacation has already been approved.
Following parameters can only be updated by Admin or Manager:

Param	Type	Description	Requirements
`is_approved`	bool	Approval state	False as default. Vacation must be approved by Admin or Managers.
`applicant_id`	int	Applicant's identification number	Gets id from request as default, but could be set by Admin or Manager.
`responder_id`	int	Responder's identification number	Gets id from request as default, but could be set by Admin or Manager.
`approval_date`	Date	Approval date	Gets date of current day as default, but could be set by Admin or Manager.

PATCH /api/v0/vacations/1 HTTP/1.1
Content-Type: application/json
        
{
    "is_approved": true,
}

Responses

200 OK

Vacation successfully updated.

PATCH /api/v0/vacations/1 HTTP/1.1
Content-Type: application/json
Status-Code: 200

{
    "id": 10,
    "vacation_from": "2022-12-28",
    "vacation_to": "2023-01-14",
    "days": 18,
    "is_approved": true,
    "note": null,
    "applicant_id": 2,
    "responder_id": 1,
    "approval_date": "2022-04-26"
}

404 NOT FOUND

Vacation was not found.

PATCH /api/v0/vacations/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "No query results for model.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

PATCH /api/v0/vacations/1 HTTP/1.1
Content-Type: application/json
Status-Code: 422

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "47da9767-7d63-4220-a98f-e802e82ddedc",
    "errors": [
        {
            "field": "vacation_to",
            "message": "datum musí být :vacation_from nebo pozdější."
        },
        {
            "field": "vacation_from",
            "message": "Datum musí být před nebo rovno :vacation_to."
        }
    ]
}

Delete vacation

DELETE /api/v0/vacations/{vacation_id}

This method needs permission delete on vacations.

Method for deleting Vacation.

Request

DELETE /api/v0/vacation/1 HTTP/1.1

Responses

204 NO CONTENT

Vacation successfully deleted.

DELETE /api/v0/vacations/1 HTTP/1.1
Status-Code: 204

404 NOT FOUND

Vacation was not found.

DELETE /api/v0/vacation/1 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

General notes​

Content​

Vacations collection

Create vacation​

POST /api/v0/vacations

Request​

Responses​

201 CREATED​

422 UNPROCESSABLE ENTITY​

Vacations index​

GET /api/v0/vacations

Request​

Responses​

200 OK​

Single vacation

Vacation detail​

GET /api/v0/vacations/{vacation_id}

Request​

Responses​

200 OK​

404 NOT FOUND​

Update vacation​

PUT/PATCH /api/v0/vacations/{vacation_id}

Request​

Responses​

200 OK​

404 NOT FOUND​

422 UNPROCESSABLE ENTITY​

Delete vacation​

DELETE /api/v0/vacations/{vacation_id}

Request​

Responses​

204 NO CONTENT​

404 NOT FOUND​

General notes

Content

Create vacation

Request

Responses

201 CREATED

422 UNPROCESSABLE ENTITY

Vacations index

Request

Responses

200 OK

Vacation detail

Request

Responses

200 OK

404 NOT FOUND

Update vacation

Request

Responses

200 OK

404 NOT FOUND

422 UNPROCESSABLE ENTITY

Delete vacation

Request

Responses

204 NO CONTENT

404 NOT FOUND