The dad-joke API

If you are thinking of starting a tech project which both allows playing around with wonderful AWS components as well as inflict pain upon those you love - or just those who happen to stand nearby - this might be the project for you: An API for serving dad jokes at any time of night or day.

There are some nice joke APIs out there since long back. For example StarWars facts and Chuck Norris jokes. I’m sure somebody has made a dad joke version too at some point, but this is my stab at it.

It was a fun project since I have wanted a way to dispense bad jokes / dad jokes on demand for many years really. They are hated by some but loved by many as well. At more than once occasion I’ve made people laugh during a demo which went wrong or while fixing some issue while people waited for me to sort out the screen share prior to a presentation. BTW: Why did the Orange stop half-way up the hill? Well, obviously it ran out of juice :)

So this is an intro to the dad joke API:

$ curl https://dadjokes.bamboozledaardvark.com/api/jokes/random
{
  "id": "a3f9b21c",
  "joke": "I'm reading a book about anti-gravity. Honestly? Can't put it down."
}

Dad Joke API is a free, no-auth, serverless HTTP endpoint that returns dad jokes. It runs on AWS, deploys in a single command, and costs roughly nothing per month. There is no database. There is no login. The whole thing fits in one Lambda.

---

What it does

There are five endpoints:

Method	Path	Description
GET	/api/jokes/random	A random joke
GET	/api/jokes/{id}	A specific joke
GET	/api/jokes	Paginated list (limit, cursor)
GET	/api/attribution	Sources and ownership notice
GET	/healthz	Health check

Joke IDs are SHA-256 hashes of the normalized joke text, truncated to 8 characters. Stable forever — bookmark /api/jokes/a3f9b21c and it’ll be the same gag in five years (assuming the API is still up, which is itself a dad joke about my projects - no guarantees!).

Around 130 jokes are bundled into the Lambda deployment package as a jokes.json file. They were curated from public r/dadjokes threads, deduplicated, and lightly rephrased for distinctness. I’m not claiming authorship of the underlying gags. Most of these are widely-circulated jokes that have been rolling around the internet for years. The rephrasings are mine though, as to not publish verbatim copies of someone else’s post.

---

The stack

The whole thing is one CloudFormation stack, defined in a ~150-line template.yaml and deployed with SAM.

Lambda (Python 3.11). Single handler, no external dependencies — stdlib only. The jokes.json file is loaded once on cold start into module-level globals; subsequent invocations are dict lookups. Cold starts are well under a second.

API Gateway HTTP API v2. The cheaper, simpler younger sibling of the original REST API: about 70% of the cost per request, less ceremony to configure, and built-in CORS. Stage-level throttling (20 req/s sustained, 50 burst by default) keeps any one client from going wild.

Amazon Certificate Manager (ACM). Free TLS certificates, as long as you can prove ownership of the domain. The SAM template requests one with DNS validation: CloudFormation creates the cert, drops a validation CNAME into Route 53, and waits for ACM to verify it. Deployment is not so bad. About 5 minutes of staring at the deploy output, no certbot, no manual renewal.

Route 53. The custom subdomain (dadjokes.bamboozledaardvark.com) is wired up with an alias A record pointing at the API Gateway domain. SAM creates this too. The custom-domain bits are all conditional on a DomainName parameter — deploy without it and you just get the default https://<id>.execute-api.<region>.amazonaws.com URL.

CloudWatch Logs. Default 7-day retention to keep the long tail of log storage cost at zero.

---

So who’s this SAM dude (or girl? - StarGate flashback!)

SAM, or the AWS Serverless Application Model, is CloudFormation with a thin layer of macros that expand the most tedious resource definitions (Lambda functions, HTTP APIs, layer attachments) into much shorter blocks. Every SAM template gets compiled into raw CloudFormation under the hood. This is great as we get the same engine, same drift detection, same stack lifecycle.

Compared to plain CloudFormation, the benefit is mainly less typing for common patterns. Compared to Terraform — for AWS-only projects — the win is that state lives inside CloudFormation rather than in a separate state file you have to babysit and lock. The flip side is that SAM is firmly AWS-only, so a multi-cloud future means a refactor.

For something like this, the deploy loop is as simple as just issuing:

make build           # sam build
make deploy          # sam deploy

From an empty AWS account to a TLS-secured public API, end-to-end, in maybe five minutes, and most of that time is waiting for the DNS validation. Subsequent updates are a lot quicker.

---

Cost

At hobby traffic — say under a million requests per month — this should run $0/month:

• Lambda free tier: 1M requests + 400k GB-seconds/month, permanently free.
• API Gateway HTTP API: free for the first 12 months up to 1M requests, then about $1 per million.
• Route 53 hosted zone: $0.50/month (already paid for the test domain).
• ACM certificates when used with API Gateway: free.
• CloudWatch Logs at 7-day retention: pennies.

The throttle defaults cap absolute worst-case spend even if someone hammers the endpoint. With no database in the picture, there’s no DynamoDB, RDS, or S3 read pricing to think about either.

---

Try it / steal it

Take it for a spin here:

curl https://dadjokes.bamboozledaardvark.com/api/jokes/random

Or visit the landing page for the docs.

The entire source for the project is on GitHub: jonas-werner/dad-joke-api. The template should reduce nicely to a daily-fact API, weather (joke?) API, or whatever else fits in a small bundled JSON file — about an hour of swapping out the data and a few rephrasings.

Hope this project will help you play with some cool AWS services, or at the very least, liven up a boring meeting or quiet family dinner.