100 lines
2.9 KiB
Markdown
100 lines
2.9 KiB
Markdown
# Holiday api
|
|
|
|
Simple api used for tracking holidays
|
|
|
|
## 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
|
|
|
|
|
|
`rangeStart|rangeEnd`
|
|
- 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. `rangeStart=2021-12-25&rangeEnd=2023-01-23`, `rangeStart=2023-01-20`
|
|
- if defined year parameter is ignored
|
|
|
|
`stateHoliday`
|
|
- 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. `stateHoliday=true`, `stateHoliday=false`
|
|
|
|
`religiousHoliday`
|
|
- 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. `religiousHoliday=true`, `religiousHoliday=false`
|
|
|
|
#### Paging
|
|
`pageSize`
|
|
- returns at most pageSize number of holidays
|
|
- eg. `pageSize=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;
|
|
},...]
|
|
}
|
|
```
|
|
eg.
|
|
```
|
|
{
|
|
"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
|
|
``` |