🎭 Jokes API

A comprehensive REST API serving over 5,000 jokes across 16 categories. Built with Go, featuring a full web interface, GraphQL support, and Swagger documentation.

Official Site: jokes.apimgr.us

About

The Jokes API provides free, open access to 5,160+ jokes across 16 different categories. No authentication required, no API keys needed - just pure comedy at your fingertips.

Features

🎯 5,160+ Jokes across 16 categories
🌐 Full Web Interface with dark/light themes
🚀 REST API with versioning (/api/v1)
🔮 GraphQL support for flexible queries
⚡ Swagger/OpenAPI documentation
📱 PWA Support for offline access
🔓 No Authentication - freely available
⚙️ File-based Configuration (YAML)
🐳 Docker ready with compose
📦 Single Static Binary with embedded assets

Production

Quick Install

Linux

curl -fsSL https://raw.githubusercontent.com/apimgr/jokes/main/scripts/install.sh | sudo bash

macOS

curl -fsSL https://raw.githubusercontent.com/apimgr/jokes/main/scripts/install.sh | bash

Windows (PowerShell as Administrator)

irm https://raw.githubusercontent.com/apimgr/jokes/main/scripts/windows.ps1 | iex

Docker Deployment

# Using docker-compose
docker-compose up -d

# Using docker directly
docker run -d \
  -p 64321:80 \
  -v ./data:/data \
  -v ./config:/config \
  --name jokes-api \
  ghcr.io/apimgr/jokes:latest

Binary Releases

Download pre-built binaries from the releases page:

Linux: jokes-api-linux-amd64, jokes-api-linux-arm64
macOS: jokes-api-darwin-amd64, jokes-api-darwin-arm64
Windows: jokes-api-windows-amd64.exe, jokes-api-windows-arm64.exe
BSD: jokes-api-freebsd-amd64, jokes-api-freebsd-arm64

Configuration

The application auto-creates configuration on first run:

Root users: /etc/apimgr/jokes/server.yaml
Regular users: ~/.config/apimgr/jokes/server.yaml

Configuration Options

server:
  host: "0.0.0.0"       # Bind address
  port: 64321           # Port (random 64xxx by default)
  rate_limit: 2000      # Requests per hour per IP

CLI Usage

# Start the server
./jokes-api

# Show help
./jokes-api --help

# Show version
./jokes-api --version

# Check status (no root required)
./jokes-api --status

# Custom port
./jokes-api --port 8080

# Custom address
./jokes-api --address 127.0.0.1

# Custom data directory
./jokes-api --data /path/to/data

Service Management

Linux (systemd)

sudo systemctl status jokes-api
sudo systemctl start jokes-api
sudo systemctl stop jokes-api
sudo systemctl restart jokes-api
sudo journalctl -u jokes-api -f

macOS (launchd)

sudo launchctl list | grep jokes
sudo launchctl unload /Library/LaunchDaemons/com.apimgr.jokes.plist
sudo launchctl load /Library/LaunchDaemons/com.apimgr.jokes.plist
tail -f /usr/local/var/log/apimgr/jokes/stdout.log

Windows (Service)

Get-Service -Name JokesAPI
Start-Service -Name JokesAPI
Stop-Service -Name JokesAPI
Restart-Service -Name JokesAPI

API Usage

REST API

# Get a random joke
curl http://localhost:64321/api/v1/jokes/random

# Get 5 random jokes
curl http://localhost:64321/api/v1/jokes/random/5

# Get joke by ID
curl http://localhost:64321/api/v1/jokes/1

# Get jokes from specific category
curl "http://localhost:64321/api/v1/jokes/random?limitTo=[nerdy]"

# Exclude explicit content
curl "http://localhost:64321/api/v1/jokes/random?exclude=explicit"

# Replace names
curl "http://localhost:64321/api/v1/jokes/random?firstName=John&lastName=Doe"

# Get all categories
curl http://localhost:64321/api/v1/jokes/categories

# Get statistics
curl http://localhost:64321/api/v1/jokes/count

# Health check
curl http://localhost:64321/healthz

GraphQL

Access GraphQL Playground at: http://localhost:64321/graphql

Example query:

query {
  randomJoke(limitTo: "[nerdy]", exclude: "explicit") {
    id
    joke
    categories
  }

  stats {
    total
    categories {
      name
      count
    }
  }
}

Swagger/OpenAPI

Interactive API documentation: http://localhost:64321/swagger

Response Format

All API responses use a consistent wrapper:

{
  "type": "success|error",
  "value": <data or error message>
}

Development

Prerequisites

Go 1.21 or higher
Git
Make (optional, for build automation)

Build from Source

# Clone repository
git clone https://github.com/apimgr/jokes.git
cd jokes

# Download dependencies
go mod download

# Build for your platform
go build -o jokes-api .

# Or use Make to build for all platforms
make build

Development Server

# Run with live reload (requires air)
go install github.com/cosmtrek/air@latest
air

# Or run directly
go run main.go

Testing

# Run tests
make test

# Or use go test directly
go test -v ./...

Building Docker Image

# Build image
make docker

# Or use docker directly
docker build -t jokes-api .

Project Structure

jokes/
├── main.go                 # Application entry point
├── go.mod                  # Go dependencies
├── Makefile                # Build automation
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker compose config
├── Jenkinsfile             # CI/CD pipeline
├── src/
│   ├── config/             # Configuration management
│   ├── models/             # Data models
│   ├── handlers/           # HTTP handlers
│   ├── routes/             # Route definitions
│   ├── web/                # Web frontend
│   │   ├── templates/      # HTML templates
│   │   └── static/         # CSS, JS, assets
│   ├── graphql/            # GraphQL schema & resolvers
│   ├── swagger/            # Swagger/OpenAPI spec
│   └── data/               # Jokes data (JSON)
├── scripts/                # Installation scripts
│   ├── install.sh          # OS-agnostic installer
│   ├── linux.sh            # Linux-specific
│   ├── macos.sh            # macOS-specific
│   └── windows.ps1         # Windows-specific
├── README.md               # This file
├── SPEC.md                 # API specification
└── LICENSE.md              # MIT License

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

Code Standards

Use go fmt for formatting
Run go vet for static analysis
Write tests for new features
Follow existing code structure

Troubleshooting

Port Already in Use

Edit server.yaml and change the port, or specify a different port via CLI:

./jokes-api --port 8080

Service Won't Start

Check logs:

Linux: sudo journalctl -u jokes-api -f
macOS: tail -f /usr/local/var/log/apimgr/jokes/stdout.log
Windows: Check Event Viewer or service logs

Binary Won't Run

Make sure the binary is executable:

chmod +x jokes-api

Configuration Not Found

The app will create default configuration automatically. If you need a custom location:

./jokes-api --config /path/to/config/dir

License

MIT License - see LICENSE.md for details.

Support

GitHub Issues: github.com/apimgr/jokes/issues
Website: jokes.apimgr.us
Documentation: Full API documentation available at /docs endpoint

Made with ❤️ by APIMGR | Part of the APIMGR Project

Category	Count	Description
animal	670	Animal-related humor
chuck-norris	593	Classic Chuck Norris jokes
nerdy	554	Programming and tech jokes
food	515	Food and cooking humor
movie	510	Film and entertainment
sports	380	Athletic and sports jokes
explicit	360	Adult humor
history	340	Historical references
work	340	Office and workplace
travel	180	Travel and tourism
general	158	General humor
medical	120	Healthcare jokes
lawyer	120	Legal profession humor
school	120	Education jokes
science	120	Scientific humor
music	80	Musical references

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Jenkinsfile		Jenkinsfile
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
SPEC.md		SPEC.md
TODO.AI.md		TODO.AI.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
release.txt		release.txt
server.yaml.example		server.yaml.example

License

apimgr/jokes

Folders and files

Latest commit

History

Repository files navigation

🎭 Jokes API

About

Features

Production

Quick Install

Linux

macOS

Windows (PowerShell as Administrator)

Docker Deployment

Binary Releases

Configuration

Configuration Options

CLI Usage

Service Management

Linux (systemd)

macOS (launchd)

Windows (Service)

API Usage

REST API

GraphQL

Swagger/OpenAPI

Categories

Response Format

Development

Prerequisites

Build from Source

Development Server

Testing

Building Docker Image

Project Structure

Contributing

Code Standards

Troubleshooting

Port Already in Use

Service Won't Start

Binary Won't Run

Configuration Not Found

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages