Fetch Jokes Endpoint Documentation

Endpoint Overview

The “Fetch Jokes” endpoint allows users to access a variety of jokes from the Best Joke API. This endpoint supports several query parameters for filtering and customizing the results.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes
• Method: GET

Required Headers

• X-RapidAPI-Key: Your unique key to authenticate with the RapidAPI service.
• X-RapidAPI-Host: The host domain for the Best Joke API, which is bestjokeapi.p.rapidapi.com.

Query Parameters

• categoryId (optional): A string to filter jokes by a specific category ID.
• include-words (optional): A string to filter jokes that include certain words.
• size (optional): An integer that specifies the number of jokes to return in one response. Defaults to 10 and is capped at a maximum of 200.
• sort-column (optional): A string that determines the column for sorting the results. Common values are createdAt and updatedAt.
• sort-order (optional): A string to define the sorting order, either asc for ascending or desc for descending. Defaults to ascending if not specified.
• after (optional): A string used as a pagination cursor to fetch records subsequent to this cursor position.

Response Structure

The response is a JSON object containing an array of jokes. Each joke object typically includes fields such as content, categoryId, userId, and status.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes?size=5&sort-column=createdAt&sort-order=asc" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace <your-key> with your actual RapidAPI key. Adjust the query parameters as needed.

Error Handling

• 400 Bad Request: If the provided query parameters are invalid.
• 401 Unauthorized: If the X-RapidAPI-Key is missing or invalid.
• 500 Internal Server Error: In case of server-side errors or issues with fetching data from the database.

---

Fetch Specific Joke Endpoint Documentation

Endpoint Overview

The “Fetch Specific Joke” endpoint is designed to retrieve a single joke by its unique identifier (joke ID) from the Best Joke API. This endpoint is particularly useful for accessing details of a specific joke.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/{jokeid}
• Method: GET

Required Headers

• X-RapidAPI-Key: Your personal API key for RapidAPI.
• X-RapidAPI-Host: The host for the Best Joke API, set to bestjokeapi.p.rapidapi.com.

Path Parameters

• jokeid: The unique identifier of the joke you want to retrieve.

Response Structure

The response is a JSON object representing the joke corresponding to the provided ID. The joke object typically includes fields such as content, categoryId, userId, and status.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes/{jokeid}" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace {jokeid} with the actual ID of the joke and <your-key> with your RapidAPI key.

Error Handling

• 400 Bad Request: If the jokeid is not provided or invalid.
• 401 Unauthorized: If the X-RapidAPI-Key is missing or incorrect.
• 404 Not Found: If a joke with the specified jokeid does not exist.
• 500 Internal Server Error: For server-side errors or issues in fetching the joke from the database.

This endpoint provides a straightforward way to access individual jokes by their unique identifiers, ensuring precise retrieval of joke data.

---

Ping Endpoint Documentation

Endpoint Overview

The “Ping” endpoint is a simple service check to verify the availability and responsiveness of the API. It returns a basic response indicating that the API is operational.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/ping
• Method: GET

Headers

• X-RapidAPI-Key: Your personal API key for accessing the RapidAPI service.
• X-RapidAPI-Host: The host for the Best Joke API on RapidAPI.

Response Format

The endpoint returns a simple JSON object with a ping: pong message, indicating that the API is active and responding.

Curl Example

curl -X GET 'https://bestjokeapi.p.rapidapi.com/jokes/ping' \
     -H 'X-RapidAPI-Key: <your-key>' \
     -H 'X-RapidAPI-Host: bestjokeapi.p.rapidapi.com'

---

Fetch Joke Categories Endpoint Documentation

Endpoint Overview

The “Fetch Joke Categories” endpoint is designed to retrieve a list of all available joke categories from the Best Joke API. This endpoint is useful for understanding the different types of jokes available and for filtering jokes by categories.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/categories
• Method: GET

Required Headers

• X-RapidAPI-Key: Your personal API key for accessing the RapidAPI service.
• X-RapidAPI-Host: The host for the Best Joke API, which is bestjokeapi.p.rapidapi.com.

Response Structure

The response is a JSON array containing the various joke categories. Each category object typically includes fields such as id, name, and description.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes/categories" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace <your-key> with your actual RapidAPI key.

Error Handling

• 401 Unauthorized: If the X-RapidAPI-Key is missing or invalid.
• 500 Internal Server Error: In case of server-side errors or issues with fetching category data from the database.

This endpoint is essential for users who want to explore different joke categories or need to filter jokes based on specific categories.

---

Fetch Random Jokes Endpoint Documentation

Endpoint Overview

The “Fetch Random Jokes” endpoint provides a way to retrieve a random selection of jokes from the Best Joke API. This endpoint is ideal for users looking for a spontaneous and varied humor experience.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/random
• Method: GET

Required Headers

• X-RapidAPI-Key: Your unique key for accessing services on RapidAPI.
• X-RapidAPI-Host: The host domain for the Best Joke API, bestjokeapi.p.rapidapi.com.

Query Parameters

• categoryId (optional): A string to specify a category ID to filter random jokes from that category.
• size (optional): An integer that determines the number of random jokes to return. The maximum value is 200.

Response Structure

The response is a JSON array containing randomly selected jokes. Each joke in the array includes details such as content, categoryId, userId, and status.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes/random?size=5&categoryId=12345" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace <your-key> with your RapidAPI key, and adjust the categoryId and size as needed.

Error Handling

• 400 Bad Request: If provided query parameters are invalid.
• 401 Unauthorized: If the X-RapidAPI-Key is missing or incorrect.
• 500 Internal Server Error: For server-side errors or issues during the random selection of jokes.

This endpoint is a great way to discover new jokes, offering random selections that can be filtered by categories or limited by number.

---

Search Jokes Endpoint Documentation

Endpoint Overview

The “Search Jokes” endpoint in the Best Joke API allows users to search for jokes based on specific keywords or phrases. This feature is particularly useful for finding jokes that match a particular topic or interest.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/search
• Method: GET

Required Headers

• X-RapidAPI-Key: Your personal API key for RapidAPI.
• X-RapidAPI-Host: The host for the Best Joke API, set to bestjokeapi.p.rapidapi.com.

Query Parameters

• query: A string representing the search term. The API will return jokes that contain this term.

Response Structure

The response is a JSON object containing an array of jokes that match the search criteria. Each joke object includes fields such as content, categoryId, userId, and status.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes/search?query=funny" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace <your-key> with your actual RapidAPI key and modify the query parameter value as needed for your search.

Error Handling

• 400 Bad Request: If the query parameter is missing or improperly formatted.
• 401 Unauthorized: If the X-RapidAPI-Key is missing or invalid.
• 500 Internal Server Error: In case of server-side errors or issues with processing the search request.

This endpoint is ideal for users who want to find jokes on specific topics, themes, or containing particular words or phrases.

---

Create New Joke Endpoint Documentation

Endpoint Overview

The “Create New Joke” endpoint allows users to generate a custom joke using specific parameters. This feature of the Best Joke API is ideal for creating jokes based on chosen themes or words.

Endpoint Details

• URL: https://bestjokeapi.p.rapidapi.com/jokes/produce
• Method: GET

Required Headers

• X-RapidAPI-Key: Your personal key for accessing RapidAPI services.
• X-RapidAPI-Host: The host for the Best Joke API, bestjokeapi.p.rapidapi.com.

Query Parameters

• include-words (optional): Words that must be included in the newly created joke.
• theme (optional): A theme around which the joke should be created.

Response Structure

The response is a JSON object containing the newly created joke. The joke object typically includes fields such as content, categoryId, userId, and status, with content being the main focus.

Curl Example

curl -X GET "https://bestjokeapi.p.rapidapi.com/jokes/produce?include-words=apple&theme=technology" \
     -H "X-RapidAPI-Key: <your-key>" \
     -H "X-RapidAPI-Host: bestjokeapi.p.rapidapi.com"

> Note: Replace <your-key> with your RapidAPI key, and adjust the include-words and theme parameters based on your preferences.

Error Handling

• 400 Bad Request: If provided query parameters are invalid.
• 401 Unauthorized: If the X-RapidAPI-Key is missing or incorrect.
• 500 Internal Server Error: For server-side errors or issues during the joke creation process.

This endpoint is excellent for users who want to generate customized jokes with specific themes or keywords.