diff --git a/README.md b/README.md index b7c38f8..2f0a7c5 100644 --- a/README.md +++ b/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 -``` - - - - Christmas - TBD - - -``` - -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 +``` + + + + Christmas + TBD + + +``` + +CSV Response +``` +id,date,name,description,is_state_holiday,is_religious_holiday +74a2a769-abf2-45d4-bdc4-442bbcc89138,2023-12-25,Christmas,TBD,true,true ``` \ No newline at end of file