Getting Started Edit

Are you looking for a way to add riddles to your application? Rather than build the feature yourself, you can use this pre-built API. The Riddles API can return riddles from a variety of categories. Current categories include easy, hard, kids, math, word, and funny. Request one random riddle or request them all! Riddles in the original database are from https://parade.com/947956/parade/riddles/. New riddles can be added and updated via the API.

Authentication

No authentication is needed to use this API.

Usage

The API’s endpoints and usage are described in the following sections:

• Get riddles in bulk or by id:
  • Get all riddles or an individual riddle
  • Get all riddles from a specific category
• Get one random riddle:
  • Select a random riddle from the database
  • Select a random riddle from a specific category
• Create or delete a riddle:
  • Add a riddle to the database
  • Delete a riddle from the database
• Modify a riddle:
  • Update an existing riddle by overwriting
  • Update a field of an existing riddle

Errors Edit

All errors will return JSON in the following format:

{
  "error": true,
  "message": "error message here"
}

/riddles Edit

To get all riddles or an individual riddle

📌 To get all riddles or an individual riddle

Use the optional id query parameter to have the corresponding Riddle object returned. Omit the query parameter to have an array of all the Riddle objects in the database returned.

The optional query parameter is defined as

Lists all the photos you have access to. You can paginate by using the parameters listed above.

Example request

A curl request to get all riddles:

curl -X GET 'https://riddlesapidoc.vercel.app/riddles'

Example request

A successful response has an HTTP status code of 200 and is an array of Riddle objects:

  HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
  {
    "_id": "60bc3ffb5dcf8ac52f16a7fd",
    "riddle": "What has to be broken before you can use it?",
    "answer": "An egg",
    "category": "easy",
    "source": "https://parade.com/947956/parade/riddles/"
  },
  {
    "_id": "60bc3ffb5dcf8ac52f16a800",
    "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
    "answer": "A candle",
    "category": "easy",
    "source": "https://parade.com/947956/parade/riddles/"
  }

The Riddle object returned uses this schema:

Possible error responses

A GET request to the /riddles endpoint may return the following errors:

$.get("http://api.myapp.com/books/", { "token": "YOUR_APP_KEY"}, function(data) {
  alert(data);
});

r = requests.get("http://api.myapp.com/books/", token="YOUR_APP_KEY")
print r.text

var request = require("request");
request("http://api.myapp.com/books?token=YOUR_APP_KEY", function (error, response, body) {
if (!error && response.statusCode == 200) {
  console.log(body);
}

curl -X GET 'https://riddlesapidoc.vercel.app/riddles'

/riddles/{category} Edit

To get all riddles from a specific category

📌 To get all riddles from a specific category

Pass the desired category as a path parameter in the request. An array of Riddle objects matching the specific category is returned.

The path parameter is defined as:

Example request

A curl request to get all riddles from the easy category:

  curl -X GET 'https://riddlesapidoc.vercel.app/riddles/easy'

Example response

A successful response is an array of Riddle objects:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  [
  {
      "_id": "60bd0708d7dcc31bd9376abe",
      "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
      "answer": "A candle",
      "category": "easy",
      "source": "https://parade.com/947956/parade/riddles/"
  }
  ]

The Riddle objects returned use this schema:

Possible error responses

A GET request to the /riddles/{category} endpoint may return the following errors:

/riddles/random Edit

To select a random riddle from the entire database

📌 To select a random riddle from the entire database:

Make a GET request. A random Riddle object from the entire database is selected and returned.

  The path parameter is defined as:

  | Parameter | Type   | Required | Description                                                                                                                                             |

Example request

A curl request to get a random riddle:

  curl -X GET 'https://riddlesapidoc.vercel.app/riddles/random'

Example response A successful response will return an HTTP status code of 200. The Riddle object returned uses this schema:

Example response

A successful response is an individual Riddle object:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

  {
  "_id": "60bd0708d7dcc31bd9376abe",
  "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
  "answer": "A candle",
  "category": "easy",
  "source": "https://parade.com/947956/parade/riddles/"
  }

Possible error responses

A GET request to the /riddles/random endpoint may return the following errors:

/riddles/{category}/random Edit

To select a random riddle from a specific category

📌 To select a random riddle from a specific category:

Pass the desired category as a path parameter in the request. A random Riddle object from the specified category will be selected and returned.

The path parameter is defined as:

Example request A curl request to get a random riddle from the easy category:

  curl -X GET 'https://riddlesapidoc.vercel.app/riddles/easy/random'

A successful response will return an HTTP status code of 200. The Riddle object returned uses this schema:

Example response

A successful response is an individual Riddle object:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

  {
  "_id": "60bd0708d7dcc31bd9376abe",
  "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
  "answer": "A candle",
  "category": "easy",
  "source": "https://parade.com/947956/parade/riddles/"
  }

Possible error responses

A GET request to the /riddles/{category}/random endpoint may return the following errors:

/riddles Edit

To add a new riddle to the database

📌 To add a new riddle to the database

Use the JSON request body to add a new Riddle object to the database.

The request body should use the following schema:

Note: The Content-Type header should be set to application/json.

Example request

A curl request to add a new riddle:

  curl -X POST \
  'https://riddlesapidoc.vercel.app/riddles' \
  -H 'Content-Type: application/json' \
  -d '{
  "riddle": "There'\''s only one word in the dictionary that'\''s spelled wrong. What is it?",
  "answer": "The word '\''wrong.'\'' It'\''s the only word that'\''s spelled W-R-O-N-G.",
  "category": "kids",
  "source": "https://www.prodigygame.com/main-en/blog/riddles-for-kids/"
  }'

A successful response will return an HTTP status code of 201 and have the following schema:

Where the Riddle object has this schema:

Example response

Example response

A successful response to a POST request is an object like below:

  HTTP/1.1 201 Created
  Content-Type: application/json; charset=utf-8

  {
  "message": "Successfully added new riddle",
  "content": {
      "_id": "60bd0708d7dcc31bd9376abe",
      "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
      "answer": "A candle",
      "category": "easy",
      "source": "https://parade.com/947956/parade/riddles/",
      "__v": 0
  }
  }

Possible error responses

A POST request to the /riddles endpoint may return the following errors.

/riddles Edit

To delete a riddle from the database

📌 To delete a riddle from the database

Select a Riddle object to delete by setting the query parameter to its id. Currently, deleting seed data (the initial riddles added to the database) is not allowed.

The query parameter is defined as:

Example request

A curl request to delete a riddle:

  curl -X DELETE 'https://riddlesapidoc.vercel.app/riddles?id=60bc3adb1e6946b94ca7a70a'

A successful response will return an HTTP status code of 200 and have the following schema:

Example response

A successful response to a DELETE request:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

  {
  "message": Successfully deleted riddle"
  }

Possible error responses

A DELETE request to the /riddles endpoint may return the following errors:

/riddles Edit

To update an existing riddle by overwriting

📌 To update an existing riddle by overwriting

Select a Riddle object to update by setting the query parameter to its id. Use the JSON request body to set new values. Fields set in the request body will overwrite all existing values. Omitting a non-required field from the request body sets that field to null. Currently, updating seed data (the initial riddles added to the database) is not allowed.

The query parameter is defined as:

The request body should use the following schema:

Note: The Content-Type header should be set to application/json.

Example request

A curl request to update (overwrite) a riddle:

  curl -X PUT \
  'http://riddlesapidoc.vercel.app/riddles?id=60bd0708d7dcc31bd9376abe' \
  -H 'Content-Type: application/json' \
  -d '{
  "riddle": "There'\''s only one word in the dictionary that'\''s spelled wrong. What is it?",
  "answer": "The word '\''wrong.'\'' It'\''s the only word that'\''s spelled W-R-O-N-G.",
  "category": "kids",
  "source": "https://www.prodigygame.com/main-en/blog/riddles-for-kids/"
  }'

A successful response will return an HTTP status code of 200 and have the following schema:

Where the Riddle object has this schema:

Example response

A successful response to a PUT request is an object like below:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

  {
  "message": "Successfully updated riddle",
  "content": {
      "_id": "60bd0708d7dcc31bd9376abe",
      "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
      "answer": "A candle",
      "category": "easy",
      "source": "https://parade.com/947956/parade/riddles/",
  }
  }

Possible error responses

A PUT request to the /riddles endpoint may return the following errors:

/riddles Edit

To update an existing riddle by overwriting

📌 To update a field of an existing riddle

Select a Riddle object to update by setting the query parameter to its id. Use the JSON request body to set one or more fields to a new value. Omitted fields retain their values. Currently, updating seed data (the initial riddles added to the database) is not allowed.

The query parameter is defined as:

The request body should use the following schema:

Note: The Content-Type header should be set to application/json.

Example request

A curl request to update a field of a riddle:

  curl -X PATCH \
  'http://riddlesapidoc.vercel.app/riddles?id=60bd0708d7dcc31bd9376abe' \
  -H 'Content-Type: application/json' \
  -d '{
  "riddle": "There'\''s only one word in the dictionary that'\''s spelled wrong. What is it?",
  "answer": "The word '\''wrong.'\'' It'\''s the only word that'\''s spelled W-R-O-N-G.",
  "category": "kids",
  "source": "https://www.prodigygame.com/main-en/blog/riddles-for-kids/"
  }'

A successful response will return an HTTP status code of 200 and have the following schema:

Where the Riddle object has this schema:

Example response

A successful response to a PATCH request is an object like below:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

  {
  "message": Successfully updated riddle",
  "content": {
      "_id": "60bd0708d7dcc31bd9376abe",
      "riddle": "I'm tall when I'm young, and I'm short when I'm old. What am I?",
      "answer": "A candle",
      "category": "easy",
      "source": "https://parade.com/947956/parade/riddles/",
  }
  }

Possible error responses

A PATCH request to the /riddles endpoint may return the following errors: