API documentation and integration tests

This project exposes a small HTTP API using Gin. Integration tests run the real router in-process via internal/httpserver.SetupRouter().

How to run integration tests

• Run all: go test -v -tags=integration ./test/integration/...
• With race detector: go test -race -v -tags=integration ./test/integration/...

Notes:

• Tests are guarded by the integration build tag so they won’t run with the default go test.

API

Base information:

• Base path: /
• Content-Type: application/json
• Error format: { "error": "message" }
• Time format: RFC3339 for createdOn fields

GET /hello

• Description: Health/sample endpoint.
• 200 OK response example:

{
  "message": "hello world"
}

POST /users

• Description: Create a new user.
• Request body:

{
  "name": "Alice"
}

• Responses:

  • 201 Created

    {
      "id": 1,
      "name": "Alice",
      "balance": 0
    }

  • 400 Bad Request

    { "error": "validation or domain error" }

GET /users/{id}

• Description: Get a user by ID.
• Path params:
  • id: integer (> 0)
• Responses:

  • 200 OK

    {
      "id": 1,
      "name": "Alice",
      "balance": 100.5
    }

  • 400 Bad Request

    { "error": "invalid id" }

  • 404 Not Found

    { "error": "user not found" }

POST /transactions/deposit

• Description: Create a deposit transaction (increase target user balance).
• Request body:

{
  "balance": 50.0,
  "toId": 1
}

• Responses:

  • 201 Created

    {
      "id": 10,
      "balance": 50.0,
      "toId": 1,
      "createdOn": "2024-01-01T12:00:00Z",
      "type": "deposit"
    }

  • 400 Bad Request

    { "error": "validation or domain error" }

POST /transactions/withdraw

• Description: Create a withdraw transaction (decrease source user balance).
• Request body:

{
  "balance": 10.0,
  "fromId": 1
}

• Responses:

  • 201 Created

    {
      "id": 11,
      "balance": 10.0,
      "fromId": 1,
      "createdOn": "2024-01-01T12:05:00Z",
      "type": "withdraw"
    }

  • 400 Bad Request

    { "error": "validation or domain error" }

POST /transactions/transfer

• Description: Create a transfer transaction (move balance between users).
• Request body:

{
  "balance": 20.0,
  "fromId": 1,
  "toId": 2
}

• Responses:

  • 201 Created

    {
      "id": 12,
      "balance": 20.0,
      "fromId": 1,
      "toId": 2,
      "createdOn": "2024-01-01T12:10:00Z",
      "type": "transfer"
    }

  • 400 Bad Request

    { "error": "validation or domain error" }

cURL examples (PowerShell)

$base = 'http://localhost:8080'

# Create user
curl -s -X POST "$base/users" `
  -H "Content-Type: application/json" `
  -d '{"name":"Alice"}'

# Get user
curl -s "$base/users/1"

# Deposit
curl -s -X POST "$base/transactions/deposit" `
  -H "Content-Type: application/json" `
  -d '{"balance":50,"toId":1}'

# Withdraw
curl -s -X POST "$base/transactions/withdraw" `
  -H "Content-Type: application/json" `
  -d '{"balance":10,"fromId":1}'

# Transfer
curl -s -X POST "$base/transactions/transfer" `
  -H "Content-Type: application/json" `
  -d '{"balance":20,"fromId":1,"toId":2}'

Run the project with Docker

Prerequisites:

• Docker Desktop installed and running.

All commands below should be executed from the repository root (the folder containing Dockerfile).

Build the image

# Build latest image
docker build --pull -t go-test-gin:latest .

Run the container

# Run in the foreground
docker run --rm -p 8080:8080 --name go-test-gin go-test-gin:latest

Or run detached:

docker run -d --rm -p 8080:8080 --name go-test-gin go-test-gin:latest

Verify the API is up

$base = 'http://localhost:8080'

# Health/sample endpoint
curl -s "$base/hello"

# Optional: create a user
curl -s -X POST "$base/users" `
  -H "Content-Type: application/json" `
  -d '{"name":"Alice"}'

Stop the container

# If running detached
docker stop go-test-gin

Notes:

• The image sets GIN_MODE=release by default. To override, run with -e GIN_MODE=debug.
• The app listens on port 8080 inside the container; map it as needed with -p <hostPort>:8080.