117 lines
3.4 KiB
Markdown
117 lines
3.4 KiB
Markdown
# Holiday api
|
|
|
|
Simple api used for tracking holidays
|
|
|
|
To check out application, open [https://holiday.bbr-dev.info](https://holiday.bbr-dev.info)
|
|
|
|
## Endpoints
|
|
|
|
Fetching is done via `GET /api/v1/holidays` endpoint
|
|
|
|
That endpoint accepts a list of required and optional parameters
|
|
|
|
### Required parameters
|
|
`country`
|
|
- determines for which country holidays are fetched, uses ISO 3166-1 Alpha-2 codes [more info here](https://en.wikipedia.org/wiki/ISO_3166-1)
|
|
- eg. `country=US`
|
|
|
|
### Optional parameters
|
|
`year`
|
|
- returns only holidays for given year
|
|
- eg. `year=2023`
|
|
- only used if no more important parameters are defined
|
|
|
|
`date`
|
|
- returns only holidays for given date
|
|
- date must be formatted in ISO 8601 format [more info here](https://www.iso.org/iso-8601-date-and-time-format.html)
|
|
- eg. `date=2021-12-25`
|
|
- if defined year and rangeStart|rangeEnd parameters are ignored
|
|
|
|
|
|
`range_start|range_end`
|
|
- returns holidays in given range with both ends being inclusive
|
|
- if either limit isn't defined it is assumed to be up to or all from given limit (if rangeStart isn't defined all holidays before rangeEnd are returned and vice-verse)
|
|
- dates must be formatted in ISO 8601 format [more info here](https://www.iso.org/iso-8601-date-and-time-format.html)
|
|
- eg. `range_start=2021-12-25&range_end=2023-01-23`, `range_start=2023-01-20`
|
|
- if defined year parameter is ignored
|
|
|
|
`state_holiday`
|
|
- if set true only holidays that are tagged as state holidays are returned, similar for if set false, if not set all holidays are returned
|
|
- eg. `state_holiday=true`, `state_holiday=false`
|
|
|
|
`religious_holiday`
|
|
- if set true only holidays that are tagged as religious holidays are returned, similar for if set false, if not set all holidays are returned
|
|
- eg. `religious_holiday=true`, `religious_holiday=false`
|
|
|
|
#### Paging
|
|
`page_size`
|
|
- returns at most pageSize number of holidays
|
|
- eg. `page_size=20`
|
|
- only applied if page is defined as well, by default set to 20
|
|
|
|
`page`
|
|
- returns nth page of holidays, paging starts at 0
|
|
- eg. `page=0`
|
|
|
|
## Response
|
|
|
|
By default, responses are returned as a json array
|
|
```
|
|
{
|
|
holidays: [{
|
|
id: string;
|
|
date: string(ISO 8601);
|
|
name: string;
|
|
description: string;
|
|
isStateHoliday: boolean;
|
|
isReligiousHoliday: boolean;
|
|
},...]
|
|
}
|
|
```
|
|
e.g.
|
|
```
|
|
{
|
|
"holidays": [{
|
|
"id": "74a2a769-abf2-45d4-bdc4-442bbcc89138",
|
|
"date": "2023-12-25",
|
|
"name": "Christmas",
|
|
"description": "TBD",
|
|
"isStateHoliday": true,
|
|
"isReligiousHoliday": true
|
|
}]
|
|
}
|
|
```
|
|
|
|
But can be returned as XML or CSV by setting appropriate `Accept` header (application/xml, text/xml or text/csv)
|
|
|
|
XML Response
|
|
```
|
|
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
|
|
<Holidays>
|
|
<Holiday id="74a2a769-abf2-45d4-bdc4-442bbcc89138" date="2023-12-25" isReligious="true" isState="true">
|
|
<name>Christmas</name>
|
|
<description>TBD</description>
|
|
</Holiday>
|
|
</Holidays>
|
|
```
|
|
|
|
CSV Response
|
|
```
|
|
id,date,name,description,is_state_holiday,is_religious_holiday
|
|
74a2a769-abf2-45d4-bdc4-442bbcc89138,2023-12-25,Christmas,TBD,true,true
|
|
```
|
|
|
|
### Development
|
|
|
|
To start server few environment variables need to be set up. This can be done by creating `.env` file with following content
|
|
|
|
```bash
|
|
PSQL_HOST=localhost
|
|
PSQL_PORT=5432
|
|
PSQL_USER=holiday
|
|
PSQL_PASSWORD=holidayPassword
|
|
PSQL_DB=holiday
|
|
|
|
PROFILE=dev,basic-auth
|
|
AUTH_KEY=holiday:holidayPassword
|
|
``` |