@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Random Riddles API
@base https://api.fungenerators.com
@version 1.5
@auth ApiKey X-Fungenerators-Api-Secret in header
@endpoints 6
@toc riddle(6)

@endpoint GET /riddle
@desc Get a Riddle entry for a given id. Retrieves a riddle question and answer based on the id.
@optional {id: str(string) # ID of the riddle to fetch}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint POST /riddle
@desc Create a random Riddle entry. Same as 'PUT' but can be used when some of the client libraries don't support 'PUT'.
@required {question: str(string) # Riddle Question, category: str(string) # Category of the riddle, answer: str(string) # Answer(s) to the riddle question}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint PUT /riddle
@desc Create a random Riddle entry.
@required {question: str(string) # Riddle Question, category: str(string) # Category of the riddle, answer: str(string) # Answer(s) to the riddle question}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint DELETE /riddle
@desc Create a random Riddle entry.
@required {id: str(string) # Riddle ID}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /riddle/random
@desc Get a random riddle for a given category(optional)
@optional {category: str(string) # Category to get the riddle from}
@returns(200) 200  response
@errors {401: 401  response}

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

@end