Joke API (RaspAPI YSWS)

Welcome to this example API for the (not yet official) RaspAPI YSWS program. This website is pretty simple, and it gives a pretty good idea on what submissions should look like. The website is pretty buggy at the moment, but clicking on the logo will take you back to this page.

Random Joke

Joke of the Day

API Documentation

Note that all examples below use the joke above inside of them. However, the API will return a random joke every time.

GET /

Parameters: None

Returns this HTML page containing a random joke and the API documentation.

Example usage:

curl https://raspapi-example.adamthegreat.hackclub.app/

Returns:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Joke API (RaspAPI YSWS)</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="/static/styles/style.css" />
    <link rel="stylesheet" href="/static/styles/darkmode.css" />
    <link rel="stylesheet" href="/static/styles/mobile.css" />
    <link rel="icon" href="/static/images/logo.png" />
    <!-- SEO Metadata -->
    <meta
      name="description"
      content="An API that serves random and generated jokes. RaspAPI YSWS Example"
    />
    <!-- Open Graph Metadata -->
    <meta
      property="og:title"
      content="Joke API (RaspAPI YSWS Example Project)"
    />
    <meta
      property="og:description"
      content="An API that serves random and generated jokes. RaspAPI YSWS Example"
    />
    <meta property="og:type" content="website" />
    <meta
      property="og:url"
      content="https://raspapi-example.adamthegreat.hackclub.app/"
    />
    <meta
      property="og:image"
      content="https://raspapi-example.adamthegreat.hackclub.app/static/images/logo.png"
    />
  </head>
  <body>
    <nav>
      <a href="/">
        <img
          src="/static/images/logo.png"
          alt="Joke Generator"
          width="100"
          height="100"
        />
      </a>
      <h1>Joke API (RaspAPI YSWS Example)</h1>
      <form action="/search-jokes" method="GET">
        <input type="text" name="query" placeholder="Search Jokes" />
        <input type="submit" value="Search" />
      </form>
    </nav>
    <p>
      Welcome to this example API for the (not yet official) RaspAPI YSWS
      program. This website is pretty simple, and it gives a pretty good idea on
      what submissions should look like. The website is pretty buggy at the
      moment, but clicking on the logo will take you back to this page.
    </p>
    <p>
      View the source code
      <a href="https://github.com/AdamEXu/JokeAPI">here</a>.
    </p>
    <h2>Random Joke</h2>
    <p class="joke"><b>Q:</b> Why do programmers hate camping?</p>
    <p class="joke"><b>A:</b> Because there are a lot of bugs.</p>
    <h2>Joke of the Day</h2>
    <p class="joke"><b>Q:</b> Why did the programmer go broke?</p>
    <p class="joke"><b>A:</b> Because he used up all his cache.</p>
    <h2>API Documentation</h2>
    <p>
      Note that all examples below use the joke above inside of them. However,
      the API will return a random joke every time.
    </p>
    <p>
      You do not have to use <inlinecode>curl</inlinecode>, you can make
      requests with any HTTP client.
    </p>
    <div class="joke">
      <b>GET /</b>
      <p>Parameters: None</p>
      <p>
        Returns this HTML page containing a random joke and the API
        documentation.
      </p>
      <p>Example usage:</p>
      <code>curl https://raspapi-example.adamthegreat.hackclub.app/</code>
      <p>Returns:</p>
      <a href="/" style="text-decoration: none"
        ><code class="small">&lt;html&gt;...&lt;/html&gt;</code></a
      >
    </div>
    <div class="joke">
      <b>POST /</b>
      <p>Parameters: None</p>
      <p>Returns a random joke in JSON format.</p>
      <p>Example usage:</p>
      <code
        >curl -X POST https://raspapi-example.adamthegreat.hackclub.app/</code
      >
      <p>Returns:</p>
      <code>{&#39;q&#39;: &#39;Why do programmers hate camping?&#39;, &#39;a&#39;: &#39;Because there are a lot of bugs.&#39;, &#39;tags&#39;: [&#39;programming&#39;, &#39;pun&#39;]}</code>
    </div>
    <div class="joke">
      <b>POST /puns</b>
      <p>Parameters: number (optional)</p>
      <p>
        Returns a list of random jokes in JSON format. If number is not given,
        returns all jokes.
      </p>
      <p>Example usage:</p>
      <!-- prettier-ignore -->
      <code
        >curl -X POST https://raspapi-example.adamthegreat.hackclub.app/puns -H "Content-Type: application/json" -d '{"number": 3}'</code
      >
      <!-- prettier-ignore -->
      <p>Returns:</p>
      <code>[{&#39;q&#39;: &#39;Why did the programmer go broke?&#39;, &#39;a&#39;: &#39;Because he used up all his cache.&#39;, &#39;tags&#39;: [&#39;programming&#39;, &#39;money&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why do pirates prefer programming in Python?&#39;, &#39;a&#39;: &#34;Because they love the &#39;arg-uments&#39;!&#34;, &#39;tags&#39;: [&#39;programming&#39;, &#39;pirates&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why was the computer cold?&#39;, &#39;a&#39;: &#39;It left its Windows open.&#39;, &#39;tags&#39;: [&#39;windows&#39;, &#39;computers&#39;, &#39;pun&#39;]}]</code>
    </div>
    <div class="joke">
      <b>POST /joke-of-the-day</b>
      <p>Parameters: date (optional)</p>
      <p>
        Returns a random joke in JSON format. If date is given, it fetches the
        joke of the day for that date. If date is not given, it fetches the joke
        of the day for today.
      </p>
      <p>Example usage:</p>
      <!-- prettier-ignore -->
      <code
        >curl -X POST http://127.0.0.1:8080/joke-of-the-day -H "Content-Type: application/json" -d '{"date": "<span id="date"></span>"}'
      </code>
      <!-- prettier-ignore -->
      <script>
        // set date to current date in YYYY-MM-DD format
        document.getElementById("date").innerHTML = new Date()
          .toISOString()
          .split("T")[0];
      </script>
      <p>Returns:</p>
      <code>{&#39;q&#39;: &#39;Why did the programmer go broke?&#39;, &#39;a&#39;: &#39;Because he used up all his cache.&#39;, &#39;tags&#39;: [&#39;programming&#39;, &#39;money&#39;, &#39;pun&#39;]}</code>
    </div>
    <div class="joke">
      <b>GET /generate-joke</b>
      <p>Parameters: prompt (optional)</p>
      <p>
        Returns a random joke in plain text. If prompt is given, it generates a
        joke relating to the prompt. If prompt is not given, it generates a
        random programming related joke.
      </p>
      <p>Example usage:</p>
      <code
        >curl
        https://raspapi-example.adamthegreat.hackclub.app/generate-joke?prompt=programming</code
      >
      <p>Returns:</p>
      <code>Q: Why do programmers hate camping?<br />A: Because there are a lot of bugs.</code>
    </div>
    <div class="joke">
      <b>POST /generate-joke</b>
      <p>Parameters: prompt (optional)</p>
      <p>
        Returns a random joke in JSON format. If prompt is given, it generates a
        joke relating to the prompt. If prompt is not given, it generates a
        random programming related joke.
      </p>
      <p>Example usage:</p>
      <!-- prettier-ignore -->
      <code
        >curl -X POST https://raspapi-example.adamthegreat.hackclub.app/generate-joke -H "Content-Type: application/json" -d '{"prompt": "something goes here"}'</code
      >
      <!-- prettier-ignore -->
      <p>Returns:</p>
      <!-- prettier-ignore -->
      <code
        >{"q": "Since generating jokes costs money, you will need to copy and paste the above into your terminal to see an actual result.", "a": "Sorry for any inconvenience.", "tags": ["money", "cost", "copy","paste"]}</code
      >
      <!-- prettier-ignore -->
    </div>
    <div class="joke">
      <b>GET /search-jokes</b>
      <p>Parameters: query</p>
      <p>
        Returns this HTML page containing a list of jokes that contain the
        query.
      </p>
      <p>Example usage:</p>
      <code
        >curl
        https://raspapi-example.adamthegreat.hackclub.app/search-jokes?query=something</code
      >
      <p>Returns:</p>
      <a href="/search-jokes?query=" style="text-decoration: none"
        ><iframe src="/search-jokes?query=" width="60%" height="300"
          >You need a browser to view this page.</iframe
        ></a
      >
    </div>
    <div class="joke">
      <b>POST /search-jokes</b>
      <p>Parameters: query, limit (optional)</p>
      <p>
        Returns a list of jokes in JSON format that contain the query. If limit
        is given, it returns at most limit jokes. If limit is not given, it
        returns at most 10 jokes.
      </p>
      <p>Example usage:</p>
      <!-- prettier-ignore -->
      <code
        >curl -X POST https://raspapi-example.adamthegreat.hackclub.app/search-jokes -H "Content-Type: application/json" -d '{"query": "something goes here", "limit": 3}'</code
      >
      <!-- prettier-ignore -->
      <p>Returns:</p>
      <code>[{&#39;q&#39;: &#39;Why did the programmer go broke?&#39;, &#39;a&#39;: &#39;Because he used up all his cache.&#39;, &#39;tags&#39;: [&#39;programming&#39;, &#39;money&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why do pirates prefer programming in Python?&#39;, &#39;a&#39;: &#34;Because they love the &#39;arg-uments&#39;!&#34;, &#39;tags&#39;: [&#39;programming&#39;, &#39;pirates&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why was the computer cold?&#39;, &#39;a&#39;: &#39;It left its Windows open.&#39;, &#39;tags&#39;: [&#39;windows&#39;, &#39;computers&#39;, &#39;pun&#39;]}]</code>
    </div>
    <div class="joke">
      <b>POST /get-jokes-by-tag</b>
      <p>Parameters: tag</p>
      <p>Returns a list of jokes in JSON format that contain the tag.</p>
      <p>Example usage:</p>
      <!-- prettier-ignore -->
      <code
        >curl -X POST https://raspapi-example.adamthegreat.hackclub.app/get-jokes-by-tag -H "Content-Type: application/json" -d '{"tag": "programming"}'</code
      >
      <!-- prettier-ignore -->
      <p>Returns:</p>
      <code>[{&#39;q&#39;: &#39;Why did the programmer go broke?&#39;, &#39;a&#39;: &#39;Because he used up all his cache.&#39;, &#39;tags&#39;: [&#39;programming&#39;, &#39;money&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why do pirates prefer programming in Python?&#39;, &#39;a&#39;: &#34;Because they love the &#39;arg-uments&#39;!&#34;, &#39;tags&#39;: [&#39;programming&#39;, &#39;pirates&#39;, &#39;pun&#39;]}, {&#39;q&#39;: &#39;Why was the computer cold?&#39;, &#39;a&#39;: &#39;It left its Windows open.&#39;, &#39;tags&#39;: [&#39;windows&#39;, &#39;computers&#39;, &#39;pun&#39;]}]</code>
    </div>
    <footer>
      <p>Made with ❤️ by <a href="https://adamxu.net/">Adam Xu</a></p>
    </footer>
  </body>
</html>

POST /

Parameters: None

Returns a random joke in JSON format.

Example usage:

curl -X POST https://raspapi-example.adamthegreat.hackclub.app/

Returns:

{'q': 'Why do programmers hate camping?', 'a': 'Because there are a lot of bugs.', 'tags': ['programming', 'pun']}

POST /puns

Parameters: number (optional)

Returns a list of random jokes in JSON format. If number is not given, returns all jokes.

Example usage:

curl -X POST https://raspapi-example.adamthegreat.hackclub.app/puns -H "Content-Type: application/json" -d '{"number": 3}'

Returns:

[{'q': 'Why did the programmer go broke?', 'a': 'Because he used up all his cache.', 'tags': ['programming', 'money', 'pun']}, {'q': 'Why do pirates prefer programming in Python?', 'a': "Because they love the 'arg-uments'!", 'tags': ['programming', 'pirates', 'pun']}, {'q': 'Why was the computer cold?', 'a': 'It left its Windows open.', 'tags': ['windows', 'computers', 'pun']}]

POST /joke-of-the-day

Parameters: date (optional)

Returns a random joke in JSON format. If date is given, it fetches the joke of the day for that date. If date is not given, it fetches the joke of the day for today.

Example usage:

curl -X POST http://127.0.0.1:8080/joke-of-the-day -H "Content-Type: application/json" -d '{"date": ""}'

Returns:

{'q': 'Why did the programmer go broke?', 'a': 'Because he used up all his cache.', 'tags': ['programming', 'money', 'pun']}

GET /generate-joke

Parameters: prompt (optional)

Returns a random joke in plain text. If prompt is given, it generates a joke relating to the prompt. If prompt is not given, it generates a random programming related joke.

Example usage:

curl
        https://raspapi-example.adamthegreat.hackclub.app/generate-joke?prompt=programming

Returns:

Q: Why do programmers hate camping?
A: Because there are a lot of bugs.

POST /generate-joke

Parameters: prompt (optional)

Returns a random joke in JSON format. If prompt is given, it generates a joke relating to the prompt. If prompt is not given, it generates a random programming related joke.

Example usage:

curl -X POST https://raspapi-example.adamthegreat.hackclub.app/generate-joke -H "Content-Type: application/json" -d '{"prompt": "something goes here"}'

Returns:

{"q": "Since generating jokes costs money, you will need to copy and paste the above into your terminal to see an actual result.", "a": "Sorry for any inconvenience.", "tags": ["money", "cost", "copy","paste"]}

GET /search-jokes

Parameters: query

Returns this HTML page containing a list of jokes that contain the query.

Example usage:

curl
        https://raspapi-example.adamthegreat.hackclub.app/search-jokes?query=something

Returns:

POST /search-jokes

Parameters: query, limit (optional)

Returns a list of jokes in JSON format that contain the query. If limit is given, it returns at most limit jokes. If limit is not given, it returns at most 10 jokes.

Example usage:

curl -X POST https://raspapi-example.adamthegreat.hackclub.app/search-jokes -H "Content-Type: application/json" -d '{"query": "something goes here", "limit": 3}'

Returns:

[{'q': 'Why did the programmer go broke?', 'a': 'Because he used up all his cache.', 'tags': ['programming', 'money', 'pun']}, {'q': 'Why do pirates prefer programming in Python?', 'a': "Because they love the 'arg-uments'!", 'tags': ['programming', 'pirates', 'pun']}, {'q': 'Why was the computer cold?', 'a': 'It left its Windows open.', 'tags': ['windows', 'computers', 'pun']}]

POST /get-jokes-by-tag

Parameters: tag

Returns a list of jokes in JSON format that contain the tag.

Example usage:

curl -X POST https://raspapi-example.adamthegreat.hackclub.app/get-jokes-by-tag -H "Content-Type: application/json" -d '{"tag": "programming"}'

Returns:

[{'q': 'Why did the programmer go broke?', 'a': 'Because he used up all his cache.', 'tags': ['programming', 'money', 'pun']}, {'q': 'Why do pirates prefer programming in Python?', 'a': "Because they love the 'arg-uments'!", 'tags': ['programming', 'pirates', 'pun']}, {'q': 'Why was the computer cold?', 'a': 'It left its Windows open.', 'tags': ['windows', 'computers', 'pun']}]