brajkovic
/
holiday-api
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases 1 Wiki Activity

Update 'README.md'

This commit is contained in:
brajkovic 2023-08-25 06:07:35 +00:00
parent 4c45d00989
commit 99c5e5cd13
1 changed files with 99 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
README.md
View File

@ -1,96 +1,100 @@
# Holiday api # Holiday api
Simple api used for tracking holidays Simple api used for tracking holidays
## Endpoints ## Endpoints
Fetching is done via `GET /api/v1/holidays` endpoint Fetching is done via `GET /api/v1/holidays` endpoint
That endpoint accepts a list of required and optional parameters That endpoint accepts a list of required and optional parameters
### Required parameters ### Required parameters
`country` `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) - 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` - eg. `country=US`
### Optional parameters ### Optional parameters
`year` `year`
- returns only holidays for given year - returns only holidays for given year
- eg. `year=2023` - eg. `year=2023`
- only used if no more important parameters are defined - only used if no more important parameters are defined
`date` `date`
- returns only holidays for given 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) - 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` - eg. `date=2021-12-25`
- if defined year and rangeStart|rangeEnd parameters are ignored - if defined year and rangeStart|rangeEnd parameters are ignored
`rangeStart|rangeEnd` `rangeStart|rangeEnd`
- returns holidays in given range with both ends being inclusive - 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) - 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) - 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` - eg. `rangeStart=2021-12-25&rangeEnd=2023-01-23`, `rangeStart=2023-01-20`
- if defined year parameter is ignored - if defined year parameter is ignored
`stateHoliday` `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 - 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` - eg. `stateHoliday=true`, `stateHoliday=false`
`religiousHoliday` `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 - 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` - eg. `religiousHoliday=true`, `religiousHoliday=false`
#### Paging #### Paging
`pageSize` `pageSize`
- returns at most pageSize number of holidays - returns at most pageSize number of holidays
- eg. `pageSize=20` - eg. `pageSize=20`
- only applied if page is defined as well, by default set to 20 - only applied if page is defined as well, by default set to 20
`page` `page`
- returns nth page of holidays, paging starts at 0 - returns nth page of holidays, paging starts at 0
- eg. `page=0` - eg. `page=0`
## Response ## Response
By default, responses are returned as a json array By default, responses are returned as a json array
``` ```
[{ {
id: string; holidays: [{
date: string(ISO 8601); id: string;
name: string; date: string(ISO 8601);
description: string; name: string;
isStateHoliday: boolean; description: string;
isReligiousHoliday: boolean; isStateHoliday: boolean;
},...] isReligiousHoliday: boolean;
``` },...]
eg. }
``` ```
[{ eg.
"id": "74a2a769-abf2-45d4-bdc4-442bbcc89138", ```
"date": "2023-12-25", {
"name": "Christmas", "holidays": [{
"description": "TBD", "id": "74a2a769-abf2-45d4-bdc4-442bbcc89138",
"isStateHoliday": true, "date": "2023-12-25",
"isReligiousHoliday": true "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" ?> But can be returned as XML or CSV by setting appropriate `Accept` header (application/xml, text/xml or text/csv)
<Holidays>
<Holiday id="74a2a769-abf2-45d4-bdc4-442bbcc89138" date="2023-12-25" isReligious="true" isState="true"> XML Response
<name>Christmas</name> ```
<description>TBD</description> <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
</Holiday> <Holidays>
</Holidays> <Holiday id="74a2a769-abf2-45d4-bdc4-442bbcc89138" date="2023-12-25" isReligious="true" isState="true">
``` <name>Christmas</name>
<description>TBD</description>
CSV Response </Holiday>
``` </Holidays>
id,date,name,description,is_state_holiday,is_religious_holiday ```
74a2a769-abf2-45d4-bdc4-442bbcc89138,2023-12-25,Christmas,TBD,true,true
CSV Response
```
id,date,name,description,is_state_holiday,is_religious_holiday
74a2a769-abf2-45d4-bdc4-442bbcc89138,2023-12-25,Christmas,TBD,true,true
``` ```