Working with JSON and APIs

The API Integration That Took 3 Days in Python, 4 Hours in Go

It was sprint planning when my manager assigned me: "Integrate with the payment provider's API. Should take a week."

In Python, I'd done this before. The pattern was familiar:

import requests
import json

def create_payment(amount, customer_id):
    response = requests.post(
        "https://api.payment.com/charges",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "amount": amount,
            "customer_id": customer_id,
            "currency": "USD"
        }
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API error: {response.text}")

But Python's dynamic typing meant runtime surprises. A missing field? Runtime error. Wrong type? Runtime error. API schema change? Production error.

In Go, I rewrote it:

type CreateChargeRequest struct {
    Amount     int    `json:"amount"`
    CustomerID string `json:"customer_id"`
    Currency   string `json:"currency"`
}

type CreateChargeResponse struct {
    ID     string `json:"id"`
    Amount int    `json:"amount"`
    Status string `json:"status"`
}

func (c *Client) CreateCharge(amount int, customerID string) (*CreateChargeResponse, error) {
    req := CreateChargeRequest{
        Amount:     amount,
        CustomerID: customerID,
        Currency:   "USD",
    }
    
    var resp CreateChargeResponse
    err := c.post("/charges", req, &resp)
    
    return &resp, err
}

The difference?

• Compile-time safety: Wrong types = won't compile

• Self-documenting: Structs show exactly what API expects

• IDE support: Autocomplete for all fields

• Zero runtime surprises: Missing fields caught before deploy

I finished the integration in 4 hours. It's been running for 2 years with zero API-related bugs.

This article covers everything I learned about JSON and APIs in Go.

---

JSON Basics

Marshaling (Go → JSON)

package main

import (
    "encoding/json"
    "fmt"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    user := User{
        ID:    1,
        Name:  "Alice",
        Email: "[email protected]",
    }
    
    // Convert to JSON
    jsonData, err := json.Marshal(user)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(string(jsonData))
    // {"id":1,"name":"Alice","email":"[email protected]"}
}

Pretty Printing

jsonData, err := json.MarshalIndent(user, "", "  ")
fmt.Println(string(jsonData))

// {
//   "id": 1,
//   "name": "Alice",
//   "email": "[email protected]"
// }

Unmarshaling (JSON → Go)

func main() {
    jsonStr := `{"id":1,"name":"Alice","email":"[email protected]"}`
    
    var user User
    err := json.Unmarshal([]byte(jsonStr), &user)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("%+v\n", user)
    // {ID:1 Name:Alice Email:[email protected]}
}

---

Struct Tags in Detail

Struct tags control JSON encoding/decoding.

Basic Tags

type User struct {
    ID        int    `json:"id"`           // Maps to "id" in JSON
    FirstName string `json:"first_name"`   // Maps to "first_name"
    LastName  string `json:"last_name"`
    Email     string `json:"email"`
}

Omit Empty Fields

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email,omitempty"`  // Omit if empty
    Phone string `json:"phone,omitempty"`  // Omit if empty
}

user := User{ID: 1, Name: "Alice"}
jsonData, _ := json.Marshal(user)
fmt.Println(string(jsonData))
// {"id":1,"name":"Alice"}
// email and phone omitted

Ignore Fields

type User struct {
    ID       int    `json:"id"`
    Name     string `json:"name"`
    Password string `json:"-"`  // Never included in JSON
}

user := User{ID: 1, Name: "Alice", Password: "secret123"}
jsonData, _ := json.Marshal(user)
fmt.Println(string(jsonData))
// {"id":1,"name":"Alice"}
// password not included

String Tags

type Product struct {
    ID    int    `json:"id,string"`     // Encode int as string
    Price int    `json:"price,string"`  // "123" instead of 123
}

product := Product{ID: 1, Price: 1999}
jsonData, _ := json.Marshal(product)
fmt.Println(string(jsonData))
// {"id":"1","price":"1999"}

Custom Field Names

type APIResponse struct {
    UserID   int    `json:"user_id"`
    UserName string `json:"user_name"`
}

---

Handling Nested JSON

Nested Structs

type Address struct {
    Street  string `json:"street"`
    City    string `json:"city"`
    ZipCode string `json:"zip_code"`
}

type User struct {
    ID      int     `json:"id"`
    Name    string  `json:"name"`
    Address Address `json:"address"`
}

// JSON:
// {
//   "id": 1,
//   "name": "Alice",
//   "address": {
//     "street": "123 Main St",
//     "city": "Springfield",
//     "zip_code": "12345"
//   }
// }

Embedded Structs

type Timestamps struct {
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Timestamps  // Embedded - fields promoted to User level
}

// JSON:
// {
//   "id": 1,
//   "name": "Alice",
//   "created_at": "2023-01-01T00:00:00Z",
//   "updated_at": "2023-01-02T00:00:00Z"
// }

Arrays and Slices

type User struct {
    ID    int      `json:"id"`
    Name  string   `json:"name"`
    Roles []string `json:"roles"`
}

// JSON:
// {
//   "id": 1,
//   "name": "Alice",
//   "roles": ["admin", "user"]
// }

Maps

type User struct {
    ID       int               `json:"id"`
    Name     string            `json:"name"`
    Metadata map[string]string `json:"metadata"`
}

// JSON:
// {
//   "id": 1,
//   "name": "Alice",
//   "metadata": {
//     "department": "Engineering",
//     "level": "Senior"
//   }
// }

---

Working with http.Client

Basic GET Request

package main

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

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func getUser(userID int) (*User, error) {
    url := fmt.Sprintf("https://api.example.com/users/%d", userID)
    
    resp, err := http.Get(url)
    if err != nil {
        return nil, fmt.Errorf("failed to fetch user: %w", err)
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("unexpected status: %d", resp.StatusCode)
    }
    
    var user User
    if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
        return nil, fmt.Errorf("failed to decode response: %w", err)
    }
    
    return &user, nil
}

POST Request

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func createUser(name, email string) (*User, error) {
    reqBody := CreateUserRequest{
        Name:  name,
        Email: email,
    }
    
    jsonData, err := json.Marshal(reqBody)
    if err != nil {
        return nil, err
    }
    
    resp, err := http.Post(
        "https://api.example.com/users",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var user User
    if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
        return nil, err
    }
    
    return &user, nil
}

Custom Headers

func getUser(userID int) (*User, error) {
    url := fmt.Sprintf("https://api.example.com/users/%d", userID)
    
    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    // Add headers
    req.Header.Set("Authorization", "Bearer "+apiToken)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("User-Agent", "MyApp/1.0")
    
    client := &http.Client{
        Timeout: 10 * time.Second,
    }
    
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var user User
    json.NewDecoder(resp.Body).Decode(&user)
    
    return &user, nil
}

---

Building a Reusable API Client

Client Structure

package apiclient

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

type Client struct {
    baseURL    string
    httpClient *http.Client
    apiKey     string
}

func NewClient(baseURL, apiKey string) *Client {
    return &Client{
        baseURL: baseURL,
        apiKey:  apiKey,
        httpClient: &http.Client{
            Timeout: 30 * time.Second,
        },
    }
}

// Generic request method
func (c *Client) doRequest(method, path string, body interface{}, result interface{}) error {
    var reqBody io.Reader
    
    if body != nil {
        jsonData, err := json.Marshal(body)
        if err != nil {
            return fmt.Errorf("failed to marshal request: %w", err)
        }
        reqBody = bytes.NewBuffer(jsonData)
    }
    
    url := c.baseURL + path
    req, err := http.NewRequest(method, url, reqBody)
    if err != nil {
        return fmt.Errorf("failed to create request: %w", err)
    }
    
    // Set headers
    req.Header.Set("Authorization", "Bearer "+c.apiKey)
    req.Header.Set("Content-Type", "application/json")
    
    // Execute request
    resp, err := c.httpClient.Do(req)
    if err != nil {
        return fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()
    
    // Check status
    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        bodyBytes, _ := io.ReadAll(resp.Body)
        return fmt.Errorf("API error %d: %s", resp.StatusCode, string(bodyBytes))
    }
    
    // Decode response
    if result != nil {
        if err := json.NewDecoder(resp.Body).Decode(result); err != nil {
            return fmt.Errorf("failed to decode response: %w", err)
        }
    }
    
    return nil
}

// Convenience methods
func (c *Client) get(path string, result interface{}) error {
    return c.doRequest("GET", path, nil, result)
}

func (c *Client) post(path string, body, result interface{}) error {
    return c.doRequest("POST", path, body, result)
}

func (c *Client) put(path string, body, result interface{}) error {
    return c.doRequest("PUT", path, body, result)
}

func (c *Client) delete(path string) error {
    return c.doRequest("DELETE", path, nil, nil)
}

Using the Client

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func (c *Client) GetUser(userID int) (*User, error) {
    var user User
    err := c.get(fmt.Sprintf("/users/%d", userID), &user)
    return &user, err
}

func (c *Client) CreateUser(name, email string) (*User, error) {
    req := map[string]string{
        "name":  name,
        "email": email,
    }
    
    var user User
    err := c.post("/users", req, &user)
    return &user, err
}

func (c *Client) UpdateUser(userID int, name, email string) (*User, error) {
    req := map[string]string{
        "name":  name,
        "email": email,
    }
    
    var user User
    err := c.put(fmt.Sprintf("/users/%d", userID), req, &user)
    return &user, err
}

func (c *Client) DeleteUser(userID int) error {
    return c.delete(fmt.Sprintf("/users/%d", userID))
}

// Usage
func main() {
    client := NewClient("https://api.example.com", "your-api-key")
    
    user, err := client.GetUser(123)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("User: %+v\n", user)
}

---

Building REST APIs with net/http

Basic HTTP Server

package main

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

type Response struct {
    Message string `json:"message"`
}

func pingHandler(w http.ResponseWriter, r *http.Request) {
    response := Response{Message: "pong"}
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

func main() {
    http.HandleFunc("/ping", pingHandler)
    
    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

CRUD API Example

package main

import (
    "encoding/json"
    "net/http"
    "strconv"
    "sync"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

type UserStore struct {
    mu    sync.RWMutex
    users map[int]*User
    nextID int
}

func NewUserStore() *UserStore {
    return &UserStore{
        users: make(map[int]*User),
        nextID: 1,
    }
}

// GET /users
func (s *UserStore) ListUsers(w http.ResponseWriter, r *http.Request) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    
    users := make([]*User, 0, len(s.users))
    for _, user := range s.users {
        users = append(users, user)
    }
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(users)
}

// GET /users/{id}
func (s *UserStore) GetUser(w http.ResponseWriter, r *http.Request) {
    idStr := r.URL.Query().Get("id")
    id, err := strconv.Atoi(idStr)
    if err != nil {
        http.Error(w, "Invalid ID", http.StatusBadRequest)
        return
    }
    
    s.mu.RLock()
    user, ok := s.users[id]
    s.mu.RUnlock()
    
    if !ok {
        http.Error(w, "User not found", http.StatusNotFound)
        return
    }
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

// POST /users
func (s *UserStore) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Name  string `json:"name"`
        Email string `json:"email"`
    }
    
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    
    s.mu.Lock()
    user := &User{
        ID:    s.nextID,
        Name:  req.Name,
        Email: req.Email,
    }
    s.users[user.ID] = user
    s.nextID++
    s.mu.Unlock()
    
    w.Header().Set("Content-Type", "application/json")
    w.WriteStatus(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

// DELETE /users/{id}
func (s *UserStore) DeleteUser(w http.ResponseWriter, r *http.Request) {
    idStr := r.URL.Query().Get("id")
    id, err := strconv.Atoi(idStr)
    if err != nil {
        http.Error(w, "Invalid ID", http.StatusBadRequest)
        return
    }
    
    s.mu.Lock()
    delete(s.users, id)
    s.mu.Unlock()
    
    w.WriteHeader(http.StatusNoContent)
}

func main() {
    store := NewUserStore()
    
    http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            store.ListUsers(w, r)
        case http.MethodPost:
            store.CreateUser(w, r)
        default:
            http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        }
    })
    
    http.HandleFunc("/users/", func(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            store.GetUser(w, r)
        case http.MethodDelete:
            store.DeleteUser(w, r)
        default:
            http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        }
    })
    
    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

---

Middleware Pattern

type Middleware func(http.Handler) http.Handler

// Logging middleware
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        
        // Call next handler
        next.ServeHTTP(w, r)
        
        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
    })
}

// Authentication middleware
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        
        if token == "" {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }
        
        // Validate token (simplified)
        if !isValidToken(token) {
            http.Error(w, "Invalid token", http.StatusUnauthorized)
            return
        }
        
        next.ServeHTTP(w, r)
    })
}

// CORS middleware
func CORSMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "*")
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
        
        if r.Method == "OPTIONS" {
            w.WriteHeader(http.StatusOK)
            return
        }
        
        next.ServeHTTP(w, r)
    })
}

// Chain middlewares
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/api/users", handleUsers)
    
    // Apply middlewares
    handler := LoggingMiddleware(
        CORSMiddleware(
            AuthMiddleware(mux),
        ),
    )
    
    log.Fatal(http.ListenAndServe(":8080", handler))
}

---

Error Handling in HTTP

type ErrorResponse struct {
    Error   string `json:"error"`
    Message string `json:"message"`
    Code    int    `json:"code"`
}

func respondWithError(w http.ResponseWriter, code int, message string) {
    response := ErrorResponse{
        Error:   http.StatusText(code),
        Message: message,
        Code:    code,
    }
    
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(response)
}

func handleGetUser(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(r.URL.Query().Get("id"))
    if err != nil {
        respondWithError(w, http.StatusBadRequest, "Invalid user ID")
        return
    }
    
    user, err := getUserFromDB(id)
    if err != nil {
        if err == sql.ErrNoRows {
            respondWithError(w, http.StatusNotFound, "User not found")
        } else {
            respondWithError(w, http.StatusInternalServerError, "Database error")
        }
        return
    }
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

---

Real Example: GitHub API Client

Complete GitHub API client I built for a project:

package github

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

type Client struct {
    baseURL    string
    httpClient *http.Client
    token      string
}

func NewClient(token string) *Client {
    return &Client{
        baseURL: "https://api.github.com",
        token:   token,
        httpClient: &http.Client{
            Timeout: 15 * time.Second,
        },
    }
}

type Repository struct {
    ID          int       `json:"id"`
    Name        string    `json:"name"`
    FullName    string    `json:"full_name"`
    Description string    `json:"description"`
    Stars       int       `json:"stargazers_count"`
    Forks       int       `json:"forks_count"`
    Language    string    `json:"language"`
    CreatedAt   time.Time `json:"created_at"`
    UpdatedAt   time.Time `json:"updated_at"`
}

func (c *Client) GetRepository(owner, repo string) (*Repository, error) {
    url := fmt.Sprintf("%s/repos/%s/%s", c.baseURL, owner, repo)
    
    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Authorization", "token "+c.token)
    req.Header.Set("Accept", "application/vnd.github.v3+json")
    
    resp, err := c.httpClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("API returned status %d", resp.StatusCode)
    }
    
    var repository Repository
    if err := json.NewDecoder(resp.Body).Decode(&repository); err != nil {
        return nil, fmt.Errorf("failed to decode response: %w", err)
    }
    
    return &repository, nil
}

func (c *Client) ListUserRepositories(username string) ([]*Repository, error) {
    url := fmt.Sprintf("%s/users/%s/repos", c.baseURL, username)
    
    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Authorization", "token "+c.token)
    req.Header.Set("Accept", "application/vnd.github.v3+json")
    
    resp, err := c.httpClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var repos []*Repository
    if err := json.NewDecoder(resp.Body).Decode(&repos); err != nil {
        return nil, err
    }
    
    return repos, nil
}

// Usage
func main() {
    client := NewClient("your-github-token")
    
    repo, err := client.GetRepository("golang", "go")
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("%s: %d stars, %d forks\n", repo.FullName, repo.Stars, repo.Forks)
}

---

Your Challenge

Build a weather API client:

// Requirements:
// 1. Create client for OpenWeatherMap API
// 2. Implement GetCurrentWeather(city string)
// 3. Implement GetForecast(city string, days int)
// 4. Handle API errors gracefully
// 5. Add proper timeouts
// 6. Use struct tags for JSON mapping
// 7. Write tests for the client

// Bonus:
// - Add caching
// - Add retry logic
// - Support multiple units (metric/imperial)

---

Key Takeaways

1. json.Marshal/Unmarshal: Convert between Go and JSON

2. Struct tags: Control JSON field names and behavior

3. http.Client: Make HTTP requests with proper configuration

4. Reusable clients: Build generic API client structure

5. net/http: Build REST APIs with standard library

6. Middleware: Chain handlers for cross-cutting concerns

7. Error handling: Return structured errors in JSON

8. Type safety: Compile-time checking prevents runtime errors

---

What I Learned

That payment API integration taught me that Go's approach to APIs is superior:

• Type safety caught bugs at compile time, not in production

• Struct tags made JSON mapping explicit and clear

• 4-hour integration vs. 3-day Python integration

• Zero API bugs in 2 years of production use

Coming from Python's dynamic typing and runtime surprises, Go's compile-time safety was revelatory. The payment integration has processed $12M in transactions without a single JSON-related bug.

The time saved debugging API issues? Weeks.

---

Next: Database Operations

In the next article, we'll dive into database operations. You'll learn connection pooling, prepared statements, transactions, and the PostgreSQL integration that handles 50,000 queries per second.