If you’ve ever been developing an application that needs to handle various HTTP status codes, you know how cumbersome it can be to simulate different server responses. I often found myself in situations where I needed to test how my applications would handle specific HTTP codes like 404, 500, or even the less common ones like 418 (I’m a teapot). After facing this challenge multiple times, I decided to create a simple solution: HTTP Codes OnDemand.

What is HTTP Codes OnDemand?

HTTP Codes OnDemand is a lightweight, containerized service that allows developers to test and simulate any valid HTTP response code. The concept is straightforward - you request a specific HTTP code, and the service responds with that exact code, along with relevant information about it.

The key features of this service include:

• Returns any standard HTTP status code (1xx, 2xx, 3xx, 4xx, 5xx)
• Provides an actual HTTP response with the requested code
• Displays information about the code, including its official specification
• Packaged as a Docker container for easy deployment

How It Works

At its core, the service is a simple PHP application that reads the requested code from a query parameter, validates it against a list of standard HTTP codes, and then sends the appropriate response. The implementation is minimal, focusing on being lightweight and easy to use.

Here’s how you can use it:

Start the container:

docker run -d -p 80:80 roura/http-codes-ondemand

Request a specific HTTP code:

GET http://localhost/?code=404

1. You’ll receive a response with:
   • The actual HTTP status code set to 404
   • A page showing “HTTP/1.1 404 Not Found”
   • A link to the official specification
   • A description of the status code

Use Cases

This tool is particularly useful for:

• Testing error handling - Ensure your application correctly handles various HTTP errors
• Simulating API responses - Test how your frontend reacts to different backend statuses
• Educational purposes - Learn about the different HTTP status codes and their meanings
• Development environments - Create predictable HTTP responses for testing scenarios

Behind the Scenes

The implementation is deliberately minimal. It consists of a small PHP script that:

1. Reads the requested code from the URL parameter
2. Validates it against a JSON file containing all standard HTTP codes
3. Sets the appropriate HTTP header for the response
4. Renders a simple HTML page with information about the requested code

The entire service is containerized using Docker, making it portable and easy to deploy in any environment.

Getting Started

You have two options to run HTTP Codes OnDemand:

Option 1: Use the pre-built Docker image

The simplest approach is to use the public Docker image:

docker run -d -p 80:80 roura/http-codes-ondemand

Option 2: Clone and run locally

If you prefer to examine or modify the code:

git clone https://github.com/rouralberto/http_codes_ondemand.git
cd http_codes_ondemand
docker-compose up -d

Once running, simply access http://localhost/?code=XXX where XXX is any valid HTTP status code.

Contribute

The project is open source and available on GitHub. If you want to contribute or have any suggestions, feel free to check out the repository.