Universal API Response Microservice

A configurable API microservice written in Go that maps requested paths to specific responses based on YAML configuration. Some sort of simple mock-service.

Features

• Map HTTP paths to specific JSON responses and status codes
• Configuration via YAML file
• Support for both HTTP and HTTPS
• Kubernetes test deployment with manifests
• Helm chart for easy deployment and configuration

Configuration

The API is configured using a YAML file that defines the path-to-response mappings:

port: "8080"
responseMappings:
  - path: "/api/v1/hello"
    response:
      message: "Hello, World!"
    status: 200
  - path: "/api/v1/users"
    response:
      users:
        - id: 1
          name: "John Doe"
        - id: 2
          name: "Jane Smith"
    status: 200

Complex Response Example

YAML format allows for defining complex, nested response structures with ease:

responseMappings:
  - path: "/api/v1/products"
    response:
      products:
        - id: 101
          name: "Premium Widget"
          price: 24.99
          details:
            color: "blue"
            weight: "150g"
            inStock: true
            features:
              - "Durable"
              - "Water resistant"
              - "5 year warranty"
        - id: 102
          name: "Economy Widget"
          price: 12.99
          details:
            color: "red"
            weight: "100g"
            inStock: true
            features:
              - "Lightweight"
              - "Recyclable"
    status: 200

These YAML-defined responses will be automatically converted to JSON when sent to the client.

Command-line Arguments

The service accepts the following command-line arguments:

• --config: Path to the configuration file (default: /etc/uniapi/config.yaml)
• --tls-cert: Path to the TLS certificate file for HTTPS
• --tls-key: Path to the TLS key file for HTTPS

Quick Start

Building the Application

Option 1: Using the build script (recommended)

The build script handles dependency management and vendoring:

# Make the build script executable
chmod +x build.sh

# Run the build script
./build.sh

Option 2: Manual build

# Download dependencies
go mod tidy
go mod vendor

# Build the binary
go build -mod=vendor -o uniapi ./cmd/uniapi

# Build Docker image
docker build -t uniapi:latest -f Dockerfile.offline .

Running Locally

# HTTP only mode
./uniapi --config=your-config.yaml

# HTTPS mode
./uniapi --config=your-config.yaml --tls-cert=cert.pem --tls-key=key.pem

Kubernetes Deployment Options

Direct Kubernetes Deployment

1. Create the TLS certificates (if needed):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=uniapi.example.com"
kubectl create secret tls uniapi-tls --cert=tls.crt --key=tls.key

2. Deploy the application:

kubectl apply -f kubernetes/

Helm Chart Deployment

The Helm chart provides a flexible way to deploy the Universal API with numerous configuration options.

Installing the Chart

helm install my-uniapi ./helm/uniapi

Customizing the Deployment

Create a custom values file:

# custom-values.yaml
replicaCount: 3

config:
  port: "8080"
  responseMappings:
    - path: "/api/v1/custom"
      response:
        status: "custom-endpoint"
      status: 200

ingress:
  domain: api.mydomain.com
  alternativeDomains:
    - api.otherdomain.com
  tls:
    enabled: true
    generateCert: true

Install with your custom values:

helm install my-uniapi ./helm/uniapi -f custom-values.yaml

Helm Chart Configuration

The Helm chart supports extensive configuration through the values.yaml file:

Image Configuration

image:
  repository: uniapi
  pullPolicy: IfNotPresent
  tag: "latest"

TLS Configuration Options

You can configure TLS in multiple ways:

1. Automatically generate self-signed certificates:

ingress:
  tls:
    enabled: true
    generateCert: true
    secretName: uniapi-tls

2. Use existing TLS secret:

ingress:
  tls:
    enabled: true
    generateCert: false
    secretName: existing-tls-secret

3. Provide certificate and key in values:

ingress:
  tls:
    enabled: true
    generateCert: false
    secretName: uniapi-tls
    certificate: "base64-encoded-certificate"
    key: "base64-encoded-key"

Domain Configuration

Configure multiple domains to access your API:

ingress:
  domain: uniapi.example.com  # Main domain
  alternativeDomains:  # Alternative domains
    - uniapi.alternative.com
    - api.example.com
  additionalHosts:  # User-defined additional hosts
    - custom.domain.com

API Response Configuration

Configure custom API responses:

config:
  responseMappings:
    - path: "/api/v1/products"
      response:
        products:
          - id: 1
            name: "Product A"
            price: 19.99
          - id: 2
            name: "Product B"
            price: 29.99
      status: 200

Accessing the API

• Within Kubernetes cluster: http://my-uniapi-uniapi/api/v1/hello
• Via Ingress:
  • HTTP: http://uniapi.example.com/api/v1/hello (will redirect to HTTPS if TLS is enabled)
  • HTTPS: https://uniapi.example.com/api/v1/hello

Customizing the API Responses

When using the Helm chart, you can customize the API responses by editing the config section in your values file.

Development

Project Structure

• /cmd/uniapi/: Application entry point
• /internal/: Internal packages
  • /config/: Configuration handling
  • /handlers/: HTTP request handlers
  • /server/: HTTP server implementation
• /kubernetes/: Kubernetes manifest files
• /helm/: Helm chart for Kubernetes deployment

Building the Project

# Build locally
go build -o uniapi ./cmd/uniapi

# Build Docker image
docker build -t uniapi:latest -f Dockerfile.offline .

Troubleshooting

Dependency Issues

If you encounter dependency issues during build:

1. Make sure you have the go.mod and go.sum files in your project
2. Run go mod tidy to clean up dependencies
3. Run go mod vendor to vendor dependencies locally
4. Use the -mod=vendor flag when building to use vendored dependencies

The provided build script handles these steps automatically.

License

This project is licensed under the MIT License - see the LICENSE file for details.