holiday-api/README.md

# 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
```