🎭 The Joke API

A blazing fast, production-ready jokes REST API built with Oak on Deno Deploy. Get random jokes, search by type, and more! 🦕 🚀

Base URL: https://joke.deno.dev

✨ Features

🚀 Fast & Reliable - Deployed on Deno Deploy edge network
🔒 CORS Enabled - Use from any domain
💾 Smart Caching - Optimized with ETag and Cache-Control headers
🛡️ Secure - Built-in security headers
📦 2900+ Jokes - Across multiple categories
🎯 Type-Safe - Written in TypeScript

📚 API Endpoints

`GET /` - Random Joke

URL: https://joke.deno.dev

Returns a random joke from the entire collection.

{
  "id": 229,
  "type": "general",
  "setup": "What do you call an alligator in a vest?",
  "punchline": "An in-vest-igator!"
}

`GET /:id` - Get Joke by ID

URL: https://joke.deno.dev/350

Get a specific joke by its ID. Perfect for saving your favorites!

{
  "id": 350,
  "type": "general",
  "setup": "Why did the tree go to the dentist?",
  "punchline": "It needed a root canal."
}

`GET /type` - List Available Types

URL: https://joke.deno.dev/type

Returns an array of all available joke types.

["general", "programming", "knock-knock", ...]

`GET /type/:type` - Get Jokes by Type

URL: https://joke.deno.dev/type/programming

Get all jokes of a specific type.

[
  {
    "id": 15,
    "type": "programming",
    "setup": "What's the best thing about a Boolean?",
    "punchline": "Even if you're wrong, you're only off by a bit."
  },
  {
    "id": 16,
    "type": "programming",
    "setup": "What's the object-oriented way to become wealthy?",
    "punchline": "Inheritance"
  },
  ...
]

`GET /type/:type/:quantity` - Get Random Jokes by Type

URL: https://joke.deno.dev/type/general/5

Get a specific number of random jokes from a category.

[
  {
    "id": 90,
    "type": "general",
    "setup": "Did you hear about the guy who invented Lifesavers?",
    "punchline": "They say he made a mint."
  }
]

`GET /all` - Get All Jokes

URL: https://joke.deno.dev/all

Returns the complete collection of jokes. Cached for optimal performance.

[
  {
    "id": 1,
    "type": "general",
    "setup": "What did the fish say when it hit the wall?",
    "punchline": "Dam."
  },
  {
    "id": 2,
    "type": "general",
    "setup": "How do you make a tissue dance?",
    "punchline": "You put a little boogie on it."
  },
  {
    "id": 3,
    "type": "general",
    "setup": "What's Forrest Gump's password?",
    "punchline": "1Forrest1"
  }
  ...
]

🚀 Quick Start

JavaScript/TypeScript

// Get a random joke
const response = await fetch("https://joke.deno.dev");
const joke = await response.json();
console.log(`${joke.setup} - ${joke.punchline}`);

Python

import requests

response = requests.get('https://joke.deno.dev')
joke = response.json()
print(f"{joke['setup']} - {joke['punchline']}")

cURL

curl https://joke.deno.dev

🔧 Development

Prerequisites

Deno 1.x or higher

Run Locally

# Clone the repository
git clone https://github.com/UltiRequiem/joke-api.git
cd joke-api

# Start the server
deno run --allow-net server/server.ts

# Server runs on http://localhost:3000

Run Tests

deno test --allow-net

📊 Analytics

Requests

January 2023, hitting around 400k requests per month.

🤝 Contributing

We welcome contributions! Here’s how you can help:

Adding New Jokes

Fork the repository
Add your joke to server/data.ts in this format:

{
  id: [last joke id + 1],
  type: "programming", // or "general", "knock-knock", etc.
  setup: "What's the best thing about a Boolean?",
  punchline: "Even if you're wrong, you're only off by a bit."
}

Submit a Pull Request

Suggesting Features

Have an idea for a new endpoint or feature? Please:

Open an issue to discuss it
Or submit a pull request with your implementation

Guidelines

Ensure jokes are appropriate and inclusive
Test your changes locally before submitting
Follow the existing code style
Update tests if needed

📖 Data Source

The initial 300 jokes came from 15Dkatz/official_joke_api. Since that project’s server went down and development ceased, we’ve maintained and grown the collection.

The collection has expanded to 2900+ jokes thanks to our amazing contributors! 🎉

Looking for more? Check out these joke APIs:

JokeAPI - Comprehensive joke API with filtering
icanhazdadjoke - Dad jokes API

📝 License

Licensed under the MIT License 📄

Made with ❤️ by UltiRequiem and contributors