JokeAPI

A simple API that returns a random joke with multi languages. Free and Open Source Joke API, entirely self-hosted.

API Reference

Get Categories List

  GET /

Response

{
    "title": "Welcome to the Joke API by arg0WAK",
    "description": "A simple API that returns a random joke",
    "endpoints": [
        {
            "url": "/:category",
            "method": "GET",
            "description": "Return jokes from /:category"
        }
    ]
}

Get Jokes from Category

  GET /:category

Response

{
    "genres": {
        "political": [
            {
                "en": { "joke": "English joke about politics." },
                "tr": { "joke": "Türkçe politik şaka." },
                "es": { "joke": "Chiste político en español." },
                "pt": { "joke": "Piada política em português." },
                "fr": { "joke": "Blague politique en français." },
                "de": { "joke": "Politischer Witz auf Deutsch." },
                "ru": { "joke": "Политическая шутка на русском." }
            }
        ]
    }
}

Postman Collection

Open with Postman

Swagger Execution

  GET /docs

Parameter	Type	Description
type	string	Defined to retrieve any subtype from genre.
lang	string	Defined to retrieve any language from subtypes.
random	boolean	Defined to receive an random joke from any subtype, subject to the requirement that a lang must be assigned.

Install and Run

Firstly clone repository on your local.

git clone git@github.com:arg0WAK/joke-api.git

Install Node 20.10.0 with Node Version Manager.

nvm install 20.10.0

Install dependencies

yarn install

Make .env file.

echo "PORT=3000" > .env

Run it.

yarn start

Run with Docker

You can also run the application with docker

docker-compose up -d --build

Update

If you're using docker:

docker pull arg0wak/joke-api

Supported Languages

Language	Available	Reviewed
Turkish	✅	✅
English	✅	✅
Spanish	✅	❌
Portuguese	✅	❌
French	✅	❌
German	✅	❌
Russian	✅	❌

Roadmap

• ⌛ API key integration.
• ⌛ Extended Rate-Limit.
• ⌛ Blacklist flags.
• ⌛ New joke categories.
• ⌛ New languages.
• ⌛ Front-end development for joke suggestions.

Enjoy it.