# QR Code API Server — v1.0.0-rc

**Release type:** Release candidate

**Release status:** Preview

This release candidate introduces a stateless, versioned QR Code API implemented in Go. It supports multiple QR payload types, authenticated access, embedded PNG responses, optional center logos, container deployment, and Kubernetes configuration.

## Highlights

### QR code formats

- URL
- vCard contact
- Wi-Fi configuration
- iCalendar event
- Plain text
- Small file as a data URI
- Number or telephone-style value
- Email
- SMS
- Geolocation

### API and security

- Versioned API namespace under `/api/v1`
- API-key authentication through `X-API-Key` or `Authorization: Bearer`
- Structured JSON success and error responses
- PNG images returned directly as Base64 and `data:image/png;base64` values
- Public `/healthz`, `/readyz`, and `/openapi.yaml` endpoints
- Request-size limits, security headers, request logging, and graceful shutdown

### Logos

- Optional custom PNG logo via JSON Base64
- Optional custom PNG logo via multipart `logo` or `logo_file` upload
- Configured fallback PNG rendered when `show_logo=true` has no custom file
- PNG signatures, dimensions, and byte limits validated before generation

### Deployment

- Multi-stage Docker image
- Non-root runtime user
- `/bin/sh` and `curl` included
- Docker health check
- Kubernetes Deployment, ConfigMap, Secret example, and Service
- GitHub Actions workflow for publishing signed GHCR images

## Installation

### Requirements

- Go 1.24 or later for source execution
- Docker 24 or later for containers
- Kubernetes 1.28 or later for the included manifests
- An API key containing at least 16 characters

### Run from Go

```bash
export API_KEY="replace-with-a-random-api-key"
go mod download
go run ./cmd/server
```

The service listens on `:8080` by default.

### Run with Docker

```bash
docker build -t qr-code-api:v1.0.0-rc .

docker run --rm \
  --name qr-code-api \
  --publish 127.0.0.1:8080:8080 \
  --env API_KEY="replace-with-a-random-api-key" \
  --env FALLBACK_LOGO_PATH="/app/assets/fallback-logo.png" \
  qr-code-api:v1.0.0-rc
```

### Deploy to Kubernetes

Create the API-key Secret, apply configuration and workloads, and check the rollout:

```bash
kubectl create secret generic qr-code-api \
  --from-literal=api-key="replace-with-a-random-api-key"

kubectl apply -f deploy/kubernetes/configmap.yaml
kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/service.yaml

kubectl rollout status deployment/qr-code-api
```

Do not apply `secret.example.yaml` with placeholder credentials. Use a secret manager or a separately generated Kubernetes Secret in production.

Full deployment details are available in [Deployment documentation](../deployment.md).

## Operation

### Health checks

```bash
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz
curl --fail http://127.0.0.1:8080/openapi.yaml
```

### Generate a QR code

```bash
curl --fail --request POST http://127.0.0.1:8080/api/v1/qr/url \
  --header "Content-Type: application/json" \
  --header "X-API-Key: replace-with-a-random-api-key" \
  --data '{
    "url": "https://example.com",
    "show_logo": true,
    "size": 256,
    "recovery": "high"
  }'
```

The response includes `qr_code.png_base64` and `qr_code.data_uri`. If no custom logo is supplied, `show_logo=true` uses `FALLBACK_LOGO_PATH`.

### Upload a custom logo

```bash
curl --fail --request POST http://127.0.0.1:8080/api/v1/qr/url \
  --header "X-API-Key: replace-with-a-random-api-key" \
  --form "url=https://example.com" \
  --form "show_logo=true" \
  --form "logo=@./logo.png;type=image/png"
```

The JSON `logo_png_base64` field provides an equivalent option for API clients that use JSON request bodies.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `API_KEY` | Required | Authentication key; minimum 16 characters |
| `LISTEN_ADDRESS` | `:8080` | HTTP listen address |
| `READ_TIMEOUT` | `10s` | HTTP read timeout |
| `WRITE_TIMEOUT` | `10s` | HTTP write timeout |
| `IDLE_TIMEOUT` | `60s` | HTTP keep-alive timeout |
| `SHUTDOWN_TIMEOUT` | `15s` | Graceful shutdown timeout |
| `FALLBACK_LOGO_PATH` | `assets/fallback-logo.png` | PNG used when `show_logo=true` has no custom logo |
| `LOGO_MAX_BYTES` | `1048576` | Maximum custom or fallback PNG size |
| `OPENAPI_PATH` | `docs/openapi.yaml` | OpenAPI file served at `/openapi.yaml` |

## Documentation

- [Project overview](../../README.md)
- [API reference](../api.md)
- [OpenAPI 3.1 specification](../openapi.yaml)
- [Deployment guide](../deployment.md)

## Known release-candidate considerations

- QR payload capacity depends on content size and recovery level.
- File QR codes support at most 1024 decoded bytes.
- Custom logos must be PNG images with dimensions from 16×16 through 1024×1024 pixels.
- The default Kubernetes image uses `latest`; immutable deployments should pin a versioned tag or image digest.
- TLS termination is expected at an ingress, gateway, or load balancer.
- API keys are secrets and must not be committed or placed in public workflow or manifest values.

## Upgrade and compatibility

This release establishes the `/api/v1` API contract. Future breaking changes should use a new version namespace and be documented separately. Clients should validate `qr_code.format`, `qr_code.size`, `qr_code.recovery`, and optional `qr_code.logo_source` fields where logo behavior is important.

## Validation

The release candidate includes unit and HTTP tests covering payload construction, PNG generation, authentication, logo behavior, JSON validation, and multipart uploads.

```bash
go test ./...
go vet ./...
go build ./...
```
