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.