@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Canada Holidays API
@base https://canada-holidays.ca
@version 1.8.0
@endpoints 6
@toc api(6)

@endpoint GET /api/v1
@desc root
@returns(200) {message: str, _links: map{self: map{href: str}, holidays: map{href: str}, provinces: map{href: str}, spec: map{href: str}}} # OK

@endpoint GET /api/v1/holidays
@desc Get all holidays
@optional {year: int=2023 # A calendar year, federal: str(1/0/true/false) # A boolean parameter. If true or 1, will return only federal holidays. If false or 0, will return no federal holidays., optional: str(1/0/true/false)=false # A boolean parameter. If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.}
@returns(200) {holidays: [map]} # OK

@endpoint GET /api/v1/provinces
@desc Get all provinces
@optional {year: int=2023 # A calendar year, optional: str(1/0/true/false)=false # A boolean parameter. If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.}
@returns(200) {provinces: [map]} # OK

@endpoint GET /api/v1/provinces/{provinceId}
@desc Get a province or territory by abbreviation
@optional {year: int=2023 # A calendar year, optional: str(1/0/true/false)=false # A boolean parameter (AB and BC only). If false or 0 (default), will return only legislated holidays. If true or 1, will return optional holidays from Alberta and BC.}
@returns(200) {province: map{id: str, nextHoliday: map{id: int, date: str(date), nameEn: str, nameFr: str, federal: int(binary), observedDate: str(date), provinces: [map], optional: int(binary)}, provinces: [map], nameFr: str, nameEn: str, sourceLink: str(uri), sourceEn: str, optional: int(binary)}} # OK
@errors {400: Bad Request}

@endpoint GET /api/v1/holidays/{holidayId}
@desc Get a holiday by id
@optional {year: int=2023 # A calendar year, optional: str(1/0/true/false)=false # A boolean parameter. If false or 0 (default), will return provinces for which this is a legislated holiday. If true or 1, will return provinces which optionally celebrate this holiday.}
@returns(200) {holiday: map{id: int, date: str(date), nameEn: str, nameFr: str, federal: int(binary), observedDate: str(date), provinces: [map], optional: int(binary)}} # OK
@errors {400: Bad Request}

@endpoint GET /api/v1/spec
@desc Get JSON schema
@returns(200) OK

@end