@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Groundhog Day API
@base https://virtserver.swaggerhub.com/pcraig3/groundhog-day-api/1.2.1
@version 1.2.1
@endpoints 5
@toc api(5)

@endpoint GET /api/v1
@desc Root
@returns(200) {message: str, _links: map{self: map{href: str}, groundhogs: map{href: str}, groundhog: map{href: str}, predictions: map{href: str}, spec: map{href: str}}} # OK

@endpoint GET /api/v1/groundhogs
@desc Get all groundhogs
@optional {country: str # Filter groundhogs by country of origin (USA or Canada)., isGroundhog: str(1/0/true/false) # Filter groundhogs by type (actual, alive groundhogs, or other prognosticators)}
@returns(200) {groundhogs: [map]} # OK

@endpoint GET /api/v1/groundhogs/{slug}
@desc Get a groundhog by slug
@returns(200) {groundhog: map{id: int, slug: str, shortname: str, name: str, city: str, region: str, country: str, coordinates: str, source: str, contact: str, currentPrediction: str, isGroundhog: int(binary), type: str, active: int(binary), description: str, image: str, predictions: [map], predictionsCount: int}} # OK
@errors {400: Bad Request}

@endpoint GET /api/v1/predictions
@desc Get predictions for a given year
@optional {year: int # A calendar year}
@returns(200) {predictions: [map]} # OK
@errors {302: Found, 400: Bad Request}

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

@end