Skip to content

Commit 9101762

Browse files
daniwebdevdaniwebdev
committed
enhance code, and docs
1 parent 3bf6f5c commit 9101762

File tree

2 files changed

+177
-211
lines changed

2 files changed

+177
-211
lines changed

‎README.md

Lines changed: 95 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,127 @@
1-
# Image Compressor API
1+
# Image Compression Service Documentation
22

33
## Overview
4+
This service allows users to download and compress images from provided URLs. It supports different image formats such as JPEG, PNG, and WebP, with optional resizing and quality adjustments. The server listens for HTTP GET requests, processes the images, and returns the compressed image files.
45

5-
Image Compressor API is a simple HTTP service written in Go that allows you to compress and resize images from a given URL. It supports popular image formats such as JPEG, PNG, and WebP.
6+
### Features:
7+
- Supports JPEG, PNG, and WebP formats.
8+
- Image resizing based on custom resolution.
9+
- Image quality adjustment for JPEG.
10+
- Caching based on MD5 hash to avoid redundant compression.
11+
- Domain whitelisting to control which sources are allowed for image download.
612

7-
## Features
13+
---
814

9-
- Image compression and resizing based on provided parameters.
10-
- Automatic determination of the image format based on the URL's content type.
11-
- Support for JPEG, PNG, and WebP output formats.
12-
- Option to specify output quality and resolution.
13-
- Efficient caching: If the compressed image already exists, it is served without re-compression.
15+
## Installation
1416

15-
## Getting Started
17+
### Prerequisites:
18+
- Go 1.18 or later.
19+
- Required Go packages:
20+
- `github.com/gorilla/mux`
21+
- `github.com/chai2010/webp`
22+
- `github.com/nfnt/resize`
1623

17-
### Prerequisites
18-
19-
- Go (Golang) installed on your machine.
20-
- [mux](https://github.com/gorilla/mux), [nfnt/resize](https://github.com/nfnt/resize), and [chai2010/webp](https://github.com/chai2010/webp) Go packages.
24+
### Clone the repository:
25+
```bash
26+
git clone <repo_url>
27+
```
2128

22-
### Installation
29+
### Install dependencies:
30+
```bash
31+
go get github.com/gorilla/mux
32+
go get github.com/chai2010/webp
33+
go get github.com/nfnt/resize
34+
```
2335

24-
1. Clone the repository:
36+
### Build the service:
37+
```bash
38+
go build -o image-compressor
39+
```
2540

26-
```bash
27-
git clone https://github.com/yourusername/your-repo.git
28-
cd your-repo
29-
```
41+
---
3042

31-
2. Install dependencies:
43+
## Usage
3244

33-
```bash
34-
go get -u github.com/gorilla/mux
35-
go get -u github.com/nfnt/resize
36-
go get -u github.com/chai2010/webp
37-
```
45+
### Command Line Flags
46+
- `-o` (default: `.`): Specifies the output directory for compressed images.
47+
- `-p` (default: `8080`): Specifies the port on which the server listens.
48+
- `-s` (default: `*`): Comma-separated list of allowed domains for downloading images. Use `*` to allow all domains.
3849

39-
3. Build and run the project:
50+
Example:
51+
```bash
52+
./image-compressor -o ./compressed-images -p 8080 -s example.com,another.com
53+
```
4054

41-
```bash
42-
go run *.go -o ./tmp
43-
```
55+
### Endpoints
4456

45-
Alternatively, for a production build:
57+
#### 1. **GET /optimize**
58+
This endpoint compresses the image from the given URL, applying optional resizing and quality adjustments. If the compressed image already exists, it is served directly without reprocessing.
4659

47-
```bash
48-
go build -o image-compressor
49-
./image-compressor -o ./tmp
50-
```
60+
##### Query Parameters:
61+
- **url** (required): The image URL to download and compress.
62+
- **output** (optional): Output image format (`jpeg`, `png`, `webp`). Defaults to the format of the original image.
63+
- **quality** (optional): JPEG quality (1-100). Only applies to JPEG format. Defaults to 75.
64+
- **resolution** (optional): Desired resolution in the format `widthxheight`. Use `auto` for either width or height to maintain aspect ratio. Example: `800x600`, `auto x 600`.
65+
- **v** (optional): Versioning parameter used to trigger new compression if image parameters have changed.
5166

52-
### Usage
67+
##### Example:
68+
```
69+
GET /optimize?url=https://example.com/image.jpg&output=webp&quality=80&resolution=800x600&v=1
70+
```
5371

54-
To compress an image, make a GET request to the `/compressor` endpoint with the following parameters:
72+
#### 2. **GET /optimize/{filename}**
73+
This endpoint retrieves an existing compressed image by its filename.
5574

56-
- `url`: URL of the image to be compressed.
57-
- `output`: Desired output format (e.g., "jpeg", "png", "webp").
58-
- `quality`: Output quality (0-100, applicable for JPEG).
59-
- `resolution`: Output resolution in the format "widthxheight" (e.g., "1024x720").
75+
##### Example:
76+
```
77+
GET /optimize/abcd1234.jpeg
78+
```
6079

61-
Example:
80+
#### 3. **GET /**
81+
A basic health check endpoint that returns `"ok!"`.
6282

63-
```bash
64-
curl "http://localhost:8080/compressor?url=https://example.com/image.jpg&output=webp&quality=80&resolution=1024x720"
83+
##### Example:
84+
```
85+
GET /
6586
```
6687

67-
## API Endpoints
88+
---
6889

69-
### `/compressor`
90+
## How It Works
7091

71-
- **Method:** GET
72-
- **Parameters:**
73-
- `url` (required): URL of the image to be compressed.
74-
- `output` (optional): Desired output format (e.g., "jpeg", "png", "webp").
75-
- `quality` (optional): Output quality (0-100, applicable for JPEG).
76-
- `resolution` (optional): Output resolution in the format "widthxheight" (e.g., "1024x720").
92+
### Image Download
93+
The `downloadImage` function downloads the image from the provided URL, checks its format, and decodes it into an image object. Supported formats are JPEG, PNG, and WebP.
7794

78-
Example:
95+
### Compression
96+
The `compressImage` function resizes the image based on the provided resolution and compresses it based on the chosen format. For JPEG, quality adjustments are possible.
7997

80-
```bash
81-
curl "http://localhost:8080/compressor?url=https://example.com/image.jpg&output=webp&quality=80&resolution=1024x720"
82-
```
98+
### MD5 Hashing
99+
The image processing parameters (URL, output format, quality, resolution, version) are concatenated into a single string and hashed using MD5 to generate a unique filename for the compressed image.
83100

84-
### Custom Port
101+
### File Caching
102+
If the compressed image file already exists, the service retrieves it directly from the output directory, avoiding redundant downloads and compressions.
85103

86-
By default, the server listens on port `8080`. If you wish to use a custom port, you can specify it during the startup of the server using the `-p` flag. For example:
104+
---
87105

88-
```bash
89-
./image-compressor -o ./tmp -p 8888
90-
```
106+
## Error Handling
107+
- If the domain of the image URL is not allowed, the service responds with a `403 Forbidden` error.
108+
- If the image format is unsupported or any other error occurs during image processing, the service responds with a `500 Internal Server Error`.
91109

92-
## License
110+
---
111+
112+
## Example Workflow
113+
114+
1. **Download and Compress Image:**
115+
```bash
116+
curl "http://localhost:8080/optimize?url=https://example.com/image.jpg&output=png&resolution=800x600&quality=90&v=1"
117+
```
93118

94-
This project is licensed under the [MIT License](LICENSE).
119+
2. **Retrieve Existing Compressed Image:**
120+
```bash
121+
curl "http://localhost:8080/optimize/<md5-hash>.png"
122+
```
123+
124+
---
125+
126+
## License
127+
This project is open source and available under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)