REST API documentation for SlimJSON daemon mode.

Overview

SlimJSON can run as an HTTP daemon to provide JSON compression as a service. This is useful for:

Starting the Daemon

# Default port 8080
slimjson -d

# Custom port
slimjson -d -port 3000

# With custom config file
slimjson -d -c /path/to/.slimjson

API Endpoints

Health Check

Check if the service is running.

Endpoint: GET /health

Response:

{
  "status": "ok",
  "version": "1.0"
}

Example:

curl http://localhost:8080/health

List Profiles

Get all available compression profiles (built-in and custom).

Endpoint: GET /profiles

Response:

{
  "builtin": [
    "light",
    "medium",
    "aggressive",
    "ai-optimized"
  ],
  "custom": [
    "my-custom-profile",
    "api-response"
  ]
}

Example:

curl http://localhost:8080/profiles

Compress JSON

Compress JSON data using a specified profile or default settings.

Endpoint: POST /slim

Query Parameters:

Request Headers:

Request Body: Any valid JSON object or array.

Response: Compressed JSON object.

Examples:

Default Compression

curl -X POST http://localhost:8080/slim \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {"id": 1, "name": "Alice", "email": "alice@example.com"},
      {"id": 2, "name": "Bob", "email": "bob@example.com"}
    ],
    "prices": [19.999, 29.123, 39.456]
  }'

Response:

{
  "prices": [20, 29, 39],
  "users": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ]
}

With Profile

curl -X POST 'http://localhost:8080/slim?profile=medium' \
  -H "Content-Type: application/json" \
  -d @data.json

With Custom Profile

curl -X POST 'http://localhost:8080/slim?profile=my-custom-profile' \
  -H "Content-Type: application/json" \
  -d @data.json

Built-in Profiles

Light

Medium

Aggressive

AI-Optimized

Error Responses

400 Bad Request

Invalid JSON or unknown profile.

"Invalid JSON: unexpected end of JSON input"

or

"Unknown profile: nonexistent"

405 Method Not Allowed

Only POST method is supported for /slim endpoint.

"Method not allowed"

OpenAPI Specification

Full OpenAPI 3.0 specification is available in swagger.yaml.

Viewing the Spec

You can view the API specification using:

Integration Examples

cURL

# Health check
curl http://localhost:8080/health

# List profiles
curl http://localhost:8080/profiles

# Compress with medium profile
curl -X POST 'http://localhost:8080/slim?profile=medium' \
  -H "Content-Type: application/json" \
  -d '{"data": "value"}'

Python

import requests

# Compress JSON
response = requests.post(
    'http://localhost:8080/slim?profile=medium',
    json={'users': [{'id': 1, 'name': 'Alice'}]}
)

compressed = response.json()
print(compressed)

JavaScript/Node.js

const fetch = require('node-fetch');

async function compressJSON(data, profile = 'medium') {
  const response = await fetch(
    `http://localhost:8080/slim?profile=${profile}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    }
  );
  
  return await response.json();
}

// Usage
const data = { users: [{ id: 1, name: 'Alice' }] };
const compressed = await compressJSON(data, 'medium');
console.log(compressed);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func compressJSON(data interface{}, profile string) (interface{}, error) {
    jsonData, err := json.Marshal(data)
    if err != nil {
        return nil, err
    }

    url := fmt.Sprintf("http://localhost:8080/slim?profile=%s", profile)
    resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result interface{}
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }

    return result, nil
}

Docker Deployment

Run SlimJSON daemon in Docker:

FROM golang:1.25-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o slimjson ./cmd/slimjson

FROM alpine:latest
COPY --from=builder /app/slimjson /usr/local/bin/
EXPOSE 8080
CMD ["slimjson", "-d", "-port", "8080"]

Build and run:

docker build -t slimjson .
docker run -p 8080:8080 slimjson

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: slimjson
spec:
  replicas: 3
  selector:
    matchLabels:
      app: slimjson
  template:
    metadata:
      labels:
        app: slimjson
    spec:
      containers:
      - name: slimjson
        image: slimjson:latest
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: slimjson
spec:
  selector:
    app: slimjson
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

Monitoring

Health Check

The /health endpoint can be used for:

Metrics

For production deployments, consider adding:

Security Considerations

  1. Rate Limiting: Implement rate limiting to prevent abuse
  2. Authentication: Add API key or JWT authentication for production
  3. HTTPS: Use TLS/SSL in production environments
  4. Input Validation: The API validates JSON but consider additional validation
  5. Resource Limits: Set appropriate memory and CPU limits

Performance

Troubleshooting

Service won’t start

# Check if port is already in use
lsof -i :8080

# Try different port
slimjson -d -port 3000

Profile not found

# List available profiles
curl http://localhost:8080/profiles

# Check config file
cat .slimjson

Invalid JSON errors

Ensure request has proper Content-Type header:

curl -X POST http://localhost:8080/slim \
  -H "Content-Type: application/json" \
  -d '{"valid": "json"}'

Support