docs: improve README with API documentation and examples

README.md

@@ -1,49 +1,134 @@
-# Video Thumbnail Service
+# vthumbs
 
-A lightweight microservice that generates JPEG thumbnails from video URLs using ffmpeg.
+vthumbs is a lightweight Node.js microservice that generates a JPEG thumbnail
+from a video URL using ffmpeg. It is designed to be simple to run, easy to
+integrate, and suitable for local development or containerized deployments.
+
+## Features
+
+- Generate a thumbnail image from a remote video URL
+- In-memory thumbnail caching for repeated requests
+- Simple HTTP API for easy integration with web and backend services
+- Fast startup with minimal configuration
+- Container-ready setup with Docker
+- Health endpoint for basic service monitoring
 
 ## Requirements
 
 - Node.js 18+
-- ffmpeg installed on the system
+- npm 9+
+- ffmpeg available on your system path (for local, non-Docker runs)
 
-## Environment Configuration
+## Quick Start
 
-Set environment variables in your shell, process manager, or deployment platform.
+Run locally in a few steps:
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `PORT` | `3100` | HTTP port used by the service |
-
-### Local Run
 
 ```bash
 npm install
 PORT=3100 npm start
 ```
 
-## Usage
+The service will be available at:
+
+```text
+http://localhost:3100
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| PORT | 3100 | HTTP port used by the service |
+
+## Docker Setup
+
+Build and run the container:
+
+```bash
+docker build -t vthumbs:local .
+docker run --rm -p 3100:3100 -e PORT=3100 vthumbs:local
+```
+
+Once running, call the API at:
+
+```text
+http://localhost:3100
+```
+
+## API Documentation
+
+### Generate Thumbnail
+
+Endpoint:
 
 ```http
-GET /thumbnail?url=https://example.com/video.mp4
+GET /thumbnail?url=VIDEO_URL
 ```
 
-Returns a JPEG image extracted at 1 second.
+#### Query Parameters
 
-## Client Configuration
+| Parameter | Required | Type | Description |
+| --- | --- | --- | --- |
+| url | Yes | string | Publicly reachable video URL to process |
 
-Configure your client app with the base URL where this service is deployed.
+Optional parameters:
 
-Example:
+- None currently
 
-```env
+#### Success Response
-THUMBNAIL_SERVICE_URL=https://your-thumbnail-service.example.com
+
+- Status: 200 OK
+- Content-Type: image/jpeg
+- Body: binary JPEG image bytes
+
+#### Error Responses
+
+| Status | Condition | Example Response |
+| --- | --- | --- |
+| 400 Bad Request | Missing url query parameter | `{ "error": "Missing 'url' query parameter" }` |
+| 500 Internal Server Error | Thumbnail generation failed | `{ "error": "Failed to generate thumbnail" }` |
+| 500 Internal Server Error | Video processing pipeline failed | `{ "error": "Failed to process video" }` |
+
+### Health Check
+
+Endpoint:
+
+```http
+GET /health
 ```
 
-## Deployment
+Response:
 
-To run your own server:
+```json
-
+{"status":"ok"}
-```sh
-docker run -d -p 3100:3100 ghcr.io/coracle-social/vthumbs:latest
 ```
+
+## Example curl Commands
+
+Generate and save a thumbnail image:
+
+```bash
+curl -L "http://localhost:3100/thumbnail?url=https://example.com/video.mp4" --output thumbnail.jpg
+```
+
+Preview response headers for a thumbnail request:
+
+```bash
+curl -I "http://localhost:3100/thumbnail?url=https://example.com/video.mp4"
+```
+
+Health check request:
+
+```bash
+curl "http://localhost:3100/health"
+```
+
+Missing required query parameter:
+
+```bash
+curl "http://localhost:3100/thumbnail"
+```
+
+## License
+
+This project is licensed under the MIT License. See LICENSE for full details.