@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Facts API
@base https://api.fungenerators.com
@version 1.5
@auth Bearer bearer
@endpoints 12
@toc fact(12)

@endpoint GET /fact
@desc Get a Fact belonging to the id.
@optional {id: str(string) # ID of the fact to fetch}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint PUT /fact
@desc Add a Fact entry to the database (private collection).
@required {fact: str(string) # Fact Text, category: str(string) # Category of the fact, subcategory: str(string) # Sub Category of the fact, tags: str(string) # Tags}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint DELETE /fact
@desc Delete a Fact entry identified by the id.
@required {id: str(string) # Fact ID}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/fod/categories
@desc Get the list of supported fact of the day categories.
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/fod
@desc Get fact of the day for the given category.
@optional {category: str(string) # Category to get the fact of the day from. Must be one from the list returned from /fact/fod/categories}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/random
@desc Get a random Fact for a given category(optional) and subcategory(optional).
@optional {category: str(string) # Category to get the fact from, subcategory: str(string) # Sub Category to get the fact from}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/search
@desc Search for random Fact which has the text in the query, for a given category(optional) and subcategory(optional).
@optional {query: str(string) # Text to search for in the facts, category: str(string) # Category to get the fact from, subcategory: str(string) # Sub Category to get the fact from}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/categories
@desc Get a random Fact.
@optional {start: int(integer) # start}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/numbers
@desc Get a random fact about a number
@required {number: int(integer) # Number value}
@returns(200) 200 Success response
@errors {401: 401 Unauthorized response}

@endpoint GET /fact/onthisday/born
@desc Returns a random ( famous/ relatively famous ) person born on a given day and month
@optional {month: str(string) # Optional month (1-12). Defaults to current month, day: str(string) # Optional day of the month (1- 28/30/31 based on the month). Defaults to current day of the month.}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/onthisday/died
@desc Returns a random ( famous/ relatively famous ) person died on a given day and month
@optional {month: str(string) # Optional month (1-12). Defaults to current month, day: str(string) # Optional day of the month (1- 28/30/31 based on the month). Defaults to current day of the month.}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /fact/onthisday/event
@desc Returns a random ( famous/ relatively famous ) historic event on a given day and month
@optional {month: str(string) # Optional month (1-12). Defaults to current month, day: str(string) # Optional day of the month (1- 28/30/31 based on the month). Defaults to current day of the month.}
@returns(200) 200  response
@errors {401: 401  response}

@end