@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Jokes One API
@base https://api.jokes.one
@version 1.1
@auth ApiKey X-JokesOne-Api-Secret in header
@endpoints 12
@toc jod(2), joke(10)

@group jod
@endpoint GET /jod
@desc Gets `Joke of the Day`.
@optional {category: any # JOD Category}
@returns(200) 200  response

@endpoint GET /jod/categories
@desc Gets a list of `Joke of the Day` Categories.
@returns(200) 200  response

@endgroup

@group joke
@endpoint PUT /joke
@desc Add a new joke to your private collection.
@required {title: any # Joke Title, text: any # Joke Text}
@optional {author: any # Joke Author, tags: any # Comma Separated tags}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint PATCH /joke
@desc Update a joke
@required {id: any # Joke ID}
@optional {title: any # title, text: any # text, author: any # Joke Author, tags: any # Comma Separated tags}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /joke
@desc Gets a `Joke` with a given `id`.
@optional {id: any # Joke ID}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint DELETE /joke
@desc Delete a joke. The user needs to be the owner of the joke to be able to delete it.
@required {id: any # Joke ID}
@returns(200) 200  response
@errors {401: 401  response, 404: 404  response}

@endpoint GET /joke/random
@desc Gets a `Random Joke`. When you are in a hurry this is what you call to get a random famous joke.
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /joke/search
@desc Search for a `Joke` in Jokes One platform. Optional `category` , `author`, `minlength`, `maxlength` params determines the filters applied while searching for the joke.
@optional {category: any # Joke Category, query: any # keyword to search for in the joke, minlength: any # Joke minimum Length, maxlength: any # Joke maximum Length, author: any # Joke Author, private: any # Should search private collection? Default searches public collection.}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint GET /joke/categories/search
@desc Gets a list of `Joke` Categories, based on a query term.
@required {query: any # Search Query}
@optional {start: any # Response is paged. This parameter controls where response starts the listing at}
@returns(200) 200  response

@endpoint GET /joke/list
@desc Get the list of jokes in your private collection.
@optional {start: any # Response is paged. This parameter controls where response starts the listing at}
@returns(200) 200  response
@errors {401: 401  response}

@endpoint POST /joke/tags/add
@desc Add a tag to a given Joke.
@required {id: any # Joke ID, tags: any # Comma Separated tags}
@returns(200) 200  response
@errors {401: 401  response, 404: 404  response}

@endpoint POST /joke/tags/remove
@desc Remove a tag from a given joke.
@required {id: any # Joke ID, tags: any # Comma Separated tags}
@returns(200) 200  response
@errors {401: 401  response, 404: 404  response}

@endgroup

@end