Go Address Book API

A Go microservice for managing user address directory with full CRUD operations and search functionality.

Features

• ✅ Create, Read, Update, Delete user addresses
• ✅ Search addresses by name, phone, email, city, or keyword
• ✅ RESTful API with JSON responses
• ✅ In-memory database (similar to H2)
• ✅ Health check endpoints via /actuator
• ✅ Code coverage with 80%+ threshold
• ✅ Docker containerization
• ✅ Helm chart for Kubernetes deployment
• ✅ Azure DevOps CI/CD pipeline

Tech Stack

• Go 1.21+
• Gorilla Mux (HTTP router)
• go-playground/validator (validation)
• testify (testing)
• In-memory storage (thread-safe)

Quick Start

Prerequisites

• Go 1.21+

Build and Run

# Clone the repository
git clone <repository-url>
cd go-addressbook-api

# Download dependencies
go mod download

# Build the application
go build -o addressbook-api ./cmd/server

# Run the application
./addressbook-api

The application will start at http://localhost:8080

Using Make

# Build
make build

# Run
make run

# Run tests
make test

# Run tests with coverage
make coverage

# Check coverage threshold (80%)
make coverage-check

Using Docker

# Build Docker image
docker build -t addressbook-api .

# Run container
docker run -p 8080:8080 addressbook-api

API Endpoints

Method	Endpoint	Description
POST	/api/addresses	Create a new address
GET	/api/addresses	Get all addresses
GET	/api/addresses/{id}	Get address by ID
PUT	/api/addresses/{id}	Update address
DELETE	/api/addresses/{id}	Delete address
GET	/api/addresses/search?q={keyword}	Search addresses
GET	/api/addresses/search/name?name={name}	Search by name
GET	/api/addresses/search/city?city={city}	Search by city

Swagger UI

Access the interactive API documentation at:

• Swagger UI: http://localhost:8080/swagger/index.html
• OpenAPI JSON: http://localhost:8080/swagger/doc.json

To regenerate Swagger docs after making changes to annotations:

swag init -g cmd/server/main.go -o docs

API Usage Examples (curl)

Create a new address

curl -X POST http://localhost:8080/api/addresses \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "1234567890",
    "email": "john@example.com",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  }'

Get all addresses

curl http://localhost:8080/api/addresses

Get address by ID

curl http://localhost:8080/api/addresses/1

Update an address

curl -X PUT http://localhost:8080/api/addresses/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "phone": "9876543210",
    "email": "john.smith@example.com",
    "street": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "zipCode": "90001",
    "country": "USA"
  }'

Delete an address

curl -X DELETE http://localhost:8080/api/addresses/1

Search addresses by keyword

# Search across all fields (name, phone, email, address, city, etc.)
curl "http://localhost:8080/api/addresses/search?q=John"

Search by name

curl "http://localhost:8080/api/addresses/search/name?name=John"

Search by city

curl "http://localhost:8080/api/addresses/search/city?city=New%20York"

Check health status

curl http://localhost:8080/actuator/health

Health Check

Access health endpoints at:

• Health: http://localhost:8080/actuator/health
• Info: http://localhost:8080/actuator/info

Testing

# Run all tests
go test ./... -v

# Run tests with coverage
go test ./... -coverprofile=coverage.out -covermode=atomic

# View coverage report
go tool cover -func=coverage.out

# Generate HTML coverage report
go tool cover -html=coverage.out -o coverage.html

Project Structure

go-addressbook-api/
├── cmd/
│   └── server/
│       └── main.go              # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go            # Configuration management
│   ├── handlers/
│   │   ├── address_handler.go   # HTTP handlers for address endpoints
│   │   ├── health_handler.go    # Health check handlers
│   │   └── handlers_test.go     # Handler unit tests
│   ├── middleware/
│   │   └── middleware.go        # Logging, error handling middleware
│   ├── models/
│   │   └── address.go           # Address model and validation
│   ├── repository/
│   │   ├── address_repo.go      # In-memory address repository
│   │   └── address_repo_test.go # Repository unit tests
│   └── service/
│       ├── address_service.go   # Business logic layer
│       └── address_service_test.go # Service unit tests
├── tests/
│   ├── integration/
│   │   └── api_integration_test.go  # Integration tests
│   └── e2e/
│       └── api_e2e_test.go      # End-to-end tests
├── helm/
│   └── addressbook/             # Helm chart files
├── Dockerfile
├── azure-pipelines.yml          # CI/CD pipeline
├── Makefile
├── go.mod
├── go.sum
└── README.md

Build for Release

To build with a specific version:

# Go build
go build -ldflags="-s -w -X main.version=1.0.0" -o addressbook-api ./cmd/server

# Docker
docker build --build-arg VERSION=1.0.0 -t addressbook-api:1.0.0 .

Deployment

Azure Container Instances

The Azure DevOps pipeline (azure-pipelines.yml) handles:

1. Build and test with code coverage
2. Docker image build and push to ACR
3. Deploy to Azure Container Instances

GitHub Actions

The GitHub Actions workflow (.github/workflows/ci-cd.yml) provides:

1. Build & Test: Compiles code, runs tests with coverage
2. Docker: Builds and pushes image to GitHub Container Registry (ghcr.io)
3. Security: Runs Gosec security scanner
4. Lint: Runs golangci-lint
5. Deploy: Helm deployment to Kubernetes (configurable)

Kubernetes (Helm)

# Install
helm install addressbook ./helm/addressbook

# Upgrade
helm upgrade addressbook ./helm/addressbook

# Uninstall
helm uninstall addressbook

Configuration

Environment variables:

Variable	Description	Default
SERVER_PORT	Application port	8080
SERVER_HOST	Server host binding	(empty = all interfaces)

License

Apache 2.0