Update 'README.md'
This commit is contained in:
parent
4c45d00989
commit
99c5e5cd13
194
README.md
194
README.md
|
|
@ -1,96 +1,100 @@
|
|||
# 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
|
||||
```
|
||||
[{
|
||||
id: string;
|
||||
date: string(ISO 8601);
|
||||
name: string;
|
||||
description: string;
|
||||
isStateHoliday: boolean;
|
||||
isReligiousHoliday: boolean;
|
||||
},...]
|
||||
```
|
||||
eg.
|
||||
```
|
||||
[{
|
||||
"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
|
||||
# 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
|
||||
```
|
||||
Loading…
Reference in New Issue