JokesAPI

Test-Driven Development with FastAPI and Docker

Description

The JokesAPI is a REST API that serves two part jokes.It supports a variety of filters that can be applied to get just the right jokes you need. It can be used without any for of API token or authentication.

Prerequisites

• Python3
• Docker and Docker compose (optional)

Setup

Docker

Clone the repository

git clone https://github.com/DanNduati/Jokes_api.git

Create a .env file similar to .env.example inside the project/ directory. Build the image and fire up the container in detached mode

$ docker compose up -d --build

Run aerich migration

$ docker compose exec web aerich upgrade

Run the tests

$ docker compose exec web python -m pytest -v

Run tests with coverage

$ docker compose exec web python -m pytest --cov="."

JokesBorrower

Ive created a joke sourcing script as well and its usage and documentation can be found here

Endpoints and Usage

1. Local BaseUrl: http://0.0.0.0:6969/
2. Heroku BaseURL: https://gentle-dusk-50795.herokuapp.com/jokes/

1. Adding/Submitting a Joke

POST /jokes/

Sample request

curl -X 'POST' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "setup": "What do you call a witch at the beach?",
    "punchline": "A Sandwich.",
    "type": "Pun"
}'

Sample response

{
  "id": 253,
  "setup": "What do you call a witch at the beach?",
  "punchline": "A Sandwich.",
  "type": "Pun"
}

2. Getting Jokes

This endpoint is the one you want to call to get joke(s).

Get Joke(s)

Filtering Jokes

The JokesAPI has versatile filtering options. There are three different filtering methods in JokeAPI:

• Joke Type
• Search string
• Joke Count
• ID Range

All of these filtering options are enforced by the following url query parameters to the /jokes endpoint:

• ?type
• ?contains
• ?count
• ?id_range

Example Usage

Joke type filter

These are all the available joke types: Misc, Programming, Dark, Pun, Spooky, Christmas. To set the category you want, you need to parse it to the query parameter ?joke_type:

?joke_type=<Joke type>

Sample request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/?joke_type=pun' \
  -H 'accept: application/json'

Sample response

[
  {
    "id": 8,
    "setup": "Thank you student loans for getting me through college.",
    "punchline": "I don't think I'll ever be able to repay you.",
    "type": "Pun"
  },
  {
    "id": 14,
    "setup": "What do you call a witch at the beach?",
    "punchline": "A Sandwich.",
    "type": "Pun"
  }
]

Search string filter

If a search string filter is used, only jokes that contain the specified string in either the setup or the punchline fields are returned. Parse the search string to the ?contains query parameter as follows:

?contains=<search string>

Sample request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/?contains=psychiatrist' \
  -H 'accept: application/json'

Sample response

[
  {
    "id": 10,
    "setup": "I told my psychiatrist I got suicidal tendencies.",
    "punchline": "He said from now on I have to pay in advance.",
    "type": "Dark"
  }
]

Joke count filter

This filter allows you to set a certain amount of jokes to receive in a single call to the Get Joke endpoint.You can set it using the ?count URL parameter. JokesAPI defaults to the maximum (10) jokes per requests 0<number<=10

?count=<number>

Sample request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/?count=5' \
  -H 'accept: application/json'

Sample response

[
  {
    "id": 1,
    "setup": "How many programmers does it take to screw in a light bulb?",
    "punchline": "None. It's a hardware problem.",
    "type": "Programming"
  },
  {
    "id": 2,
    "setup": "Why did the web developer walk out of a resturant in disgust?",
    "punchline": "The seating was laid out in tables.",
    "type": "Programming"
  },
  {
    "id": 3,
    "setup": "Why is 6 afraid of 7 in hexadecimal Canada?",
    "punchline": "Because 7 8 9 A?",
    "type": "Programming"
  },
  {
    "id": 4,
    "setup": "Programming is like sex.",
    "punchline": "Make one mistake and you end up supporting it for the rest of your life.",
    "type": "Programming"
  },
  {
    "id": 5,
    "setup": "Hey, wanna hear a joke?",
    "punchline": "Parsing HTML with regex.",
    "type": "Programming"
  }
]

ID Range filter

If an ID Range filter is used, only jokes inside the specified ID range are returned. Parse the ID range string to the ?id_range query parameter as follows:

?id_range=number-number

Sample request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/?id_range=6-9' \
  -H 'accept: application/json'

Sample response

[
  {
    "id": 6,
    "setup": "Why do programmers confuse Halloween and Christmas?",
    "punchline": "Because Oct 31 = Dec 25",
    "type": "Programming"
  },
  {
    "id": 7,
    "setup": "Why does no one like SQLrillex?",
    "punchline": "He keeps dropping the database.",
    "type": "Programming"
  },
  {
    "id": 8,
    "setup": "Thank you student loans for getting me through college.",
    "punchline": "I don't think I'll ever be able to repay you.",
    "type": "Pun"
  },
  {
    "id": 9,
    "setup": "Why is every gender equality officer female?",
    "punchline": "Because it's cheaper.",
    "type": "Misc"
  }
]

Applying multiple filters

You can combine multiple filters by combining the query parameters. The parameters need to be prefixed by a single question mark (?) and separate key/value pairs need to be delimited from another by an ampersand (&). Keys are separated from values with an equals sign (=).

Example: https://gentle-dusk-50795.herokuapp.com/jokes/?count=2&joke_type=Programming&contains=program&id_range=1-5

Request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/?count=2&joke_type=Programming&contains=program&id_range=1-5' \
  -H 'accept: application/json'

Sample response

[
  {
    "id": 1,
    "setup": "How many programmers does it take to screw in a light bulb?",
    "punchline": "None. It's a hardware problem.",
    "type": "Programming"
  },
  {
    "id": 4,
    "setup": "Programming is like sex.",
    "punchline": "Make one mistake and you end up supporting it for the rest of your life.",
    "type": "Programming"
  }
]

3. Getting a joke by id

GET /jokes/<id>/

Sample request

curl -X 'GET' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/1' \
  -H 'accept: application/json'

Sample response

{
  "id": 1,
  "setup": "How many programmers does it take to screw in a light bulb?",
  "punchline": "None. It's a hardware problem.",
  "type": "Programming"
}

4. Update a Joke by id

PUT /jokes/<id>/

Sample request

curl -X 'PUT' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/21/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "setup": "What'\''s the difference between an in-law and an outlaw?",
    "punchline": "An outlaw is wanted.",
    "type": "Misc"
}'

Sample response

{
  "id": 256,
  "setup": "What's the difference between an in-law and an outlaw?",
  "punchline": "An outlaw is wanted.",
  "type": "Misc"
}

5. Delete a Joke by id

DELETE /jokes/<id>/

Sample request

curl -X 'DELETE' \
  'https://gentle-dusk-50795.herokuapp.com/jokes/2/' \
  -H 'accept: application/json'

Sample response

{
  "message": "Deleted joke with id 2"
}

You can also interact with the endpoints at http://0.0.0.0:6969/docs

Built with

• FastAPI
• Docker
• Jokesborrower

Todo

• Implement remaining endpoints -> delete and update
• Implement id range joke filtering option
• Look into Uptime monitoring
• Experiment with rate limiting

License