QR Code API

A full-stack QR code generation platform with a robust, well-tested Go backend API and a modern Next.js TypeScript frontend.

Project Structure

• Backend: Go API with comprehensive testing (/ root directory)
• Frontend: Next.js + TypeScript UI (/frontend directory)

Features

• Multiple Formats: Generate QR codes as PNG or SVG
• Configurable Size: Customize dimensions (64-2048 pixels)
• Error Correction Levels: Support for L, M, Q, and H levels
• Base64 Encoding: Returns QR codes as base64-encoded strings
• Comprehensive Testing: Unit and integration tests with excellent coverage
• RESTful API: Clean, simple HTTP endpoints
• Health Check: Built-in health monitoring endpoint

Quick Start

Backend Setup

# Install Go dependencies
go mod download

# Run the backend server
go run main.go

The server starts on port 8080 by default. Set the PORT environment variable to use a different port:

PORT=3000 go run main.go

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Run the development server
npm run dev

Open http://localhost:3000 to use the QR code generator UI.

Full Stack Development

1. Terminal 1 - Run the backend:

   go run main.go

2. Terminal 2 - Run the frontend:

   cd frontend && npm run dev

3. Open http://localhost:3000 in your browser

API Documentation

Generate QR Code

Generate a QR code with custom configuration.

Endpoint: POST /api/qr/generate

Request Body:

{
  "content": "https://example.com",
  "size": 512,
  "error_correction_level": "H",
  "format": "png"
}

Parameters:

Field	Type	Required	Default	Description
content	string	Yes	-	Data to encode in the QR code
size	integer	No	256	Width/height in pixels (64-2048)
error_correction_level	string	No	"M"	L (~7%), M (~15%), Q (~25%), H (~30%)
format	string	No	"png"	Output format: "png" or "svg"

Note: SVG output dimensions are calculated to fit the QR code modules plus quiet zone. The actual size may be slightly smaller than requested to maintain proper module proportions.

Response:

{
  "data": "iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png",
  "size": 512
}

Response Fields:

• data: Base64-encoded QR code image
• format: Output format used
• size: Actual size of the generated QR code

Health Check

Check the API health status.

Endpoint: GET /health

Response:

{
  "status": "healthy"
}

Usage Examples

Generate a Basic QR Code

curl -X POST http://localhost:8080/api/qr/generate \
  -H "Content-Type: application/json" \
  -d '{"content":"https://example.com"}'

Generate a Large QR Code with High Error Correction

curl -X POST http://localhost:8080/api/qr/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://github.com/edwardwieczorek/qr-api",
    "size": 1024,
    "error_correction_level": "H",
    "format": "png"
  }'

Generate an SVG QR Code

curl -X POST http://localhost:8080/api/qr/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "mailto:test@example.com",
    "format": "svg"
  }'

Save QR Code to File

curl -X POST http://localhost:8080/api/qr/generate \
  -H "Content-Type: application/json" \
  -d '{"content":"https://example.com"}' \
  | jq -r '.data' \
  | base64 -d > qrcode.png

Common Use Cases

WiFi Network:

{
  "content": "WIFI:T:WPA;S:NetworkName;P:password;;",
  "error_correction_level": "H"
}

Contact Information (vCard):

{
  "content": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD"
}

Plain Text:

{
  "content": "Hello, World!"
}

Error Handling

The API returns appropriate HTTP status codes and error messages:

400 Bad Request:

• Empty content
• Invalid size (outside 64-2048 range)
• Invalid format (not "png" or "svg")
• Invalid error correction level (not L, M, Q, or H)

405 Method Not Allowed:

• Using GET instead of POST on generation endpoint

413 Request Entity Too Large:

• Content exceeds maximum length (4296 characters)

Error Response Format:

{
  "error": "Bad Request",
  "message": "content cannot be empty"
}

Testing

Run all tests:

go test -v ./...

Run tests with coverage:

go test -cover ./...

Generate coverage report:

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Project Structure

qr-api/
├── main.go                    # Application entry point
├── integration_test.go        # Integration tests
├── internal/
│   ├── handlers/              # HTTP handlers
│   │   ├── qr.go
│   │   ├── qr_test.go
│   │   └── routes.go
│   ├── models/                # Data models
│   │   └── qr.go
│   └── qr/                    # QR generation logic
│       ├── generator.go
│       └── generator_test.go
├── go.mod
└── README.md

Dependencies

• github.com/skip2/go-qrcode - QR code generation library

Configuration

Environment Variables

• PORT: Server port (default: 8080)

Constants (configurable in code)

• Default Size: 256 pixels
• Min Size: 64 pixels
• Max Size: 2048 pixels
• Max Content Length: 4296 characters
• Default Error Correction: M (Medium)

Development

Adding New Features

The codebase is organized for easy extension:

1. Add new endpoints: Update internal/handlers/routes.go
2. Add business logic: Update or create new files in internal/qr/
3. Add models: Update internal/models/qr.go
4. Write tests: Add corresponding test files

Code Quality

• All packages have comprehensive unit tests
• Integration tests cover full request/response cycles
• Error handling tested with various edge cases
• Input validation with clear error messages

License

MIT

Future Enhancements

Potential features for frontend integration:

• CORS support for browser-based clients
• Rate limiting
• Caching for frequently generated QR codes
• WebSocket support for real-time generation
• Batch generation endpoint
• QR code analytics
• Custom color schemes
• Logo/image overlay support