Fundamental HTTP
untuk Backend Developer

Sebelum bicara router, middleware, handler, dan framework, backend developer harus paham bahasa yang dipakai client dan server untuk saling bicara.

Kalau kamu datang dari React, kamu mungkin sering menulis fetch, axios.get, atau mutation di React Query. Di sisi frontend, request terlihat seperti function call ke URL. Di sisi backend Go, request itu bukan function call biasa. Ia adalah pesan HTTP yang membawa method, path, headers, query string, body, dan informasi koneksi.

Kalau kamu datang dari Laravel, kamu sudah mengenal route seperti Route::get('/products/{id}', ...), request object, response JSON, dan middleware. Go juga punya konsep yang sama, tetapi lebih dekat ke protokol dasarnya. Package standar net/http langsung memberi http.Request, http.ResponseWriter, http.Handler, dan server HTTP tanpa framework besar.

Pada proyek online shop skincare, HTTP menjadi kontrak publik untuk katalog produk, cart, checkout, order history, login, upload bukti pembayaran, dan payment webhook. Jika kontraknya kabur, frontend akan sulit dipakai, error handling berantakan, dan integrasi payment menjadi rapuh.

Setiap interaksi API dimulai dari request dan selesai dengan response.

Request adalah pesan dari client ke server. Client bisa berupa browser, React app, mobile app, cURL, Postman, worker internal, atau payment gateway. Response adalah balasan server yang memberi tahu hasilnya, sukses, gagal karena input, gagal karena hak akses, atau gagal karena server.

HTTP request sederhanaSalin
GET /v1/products?skin_type=oily&page=1 HTTP/1.1
Host: api.skincare.local
Accept: application/json
Authorization: Bearer eyJhbGciOi...
X-Request-ID: req_7HcP0W

HTTP response sederhanaSalin
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: req_7HcP0W

{
  "data": [
    { "id": "prd_001", "name": "Niacinamide Serum", "price": 129000 }
  ],
  "meta": { "page": 1, "page_size": 20 }
}

Di Go, request dibaca dari *http.Request. Path ada di r.URL.Path, method ada di r.Method, query ada di r.URL.Query(), header ada di r.Header, dan body dibaca dari r.Body. Response ditulis ke http.ResponseWriter, biasanya dengan status code, header, lalu JSON.

HTTP method menjelaskan niat request, bukan sekadar nama teknis.

Di frontend, semua bisa terlihat seperti memanggil URL. Di backend, method adalah bagian penting dari kontrak. GET /v1/products dan POST /v1/products boleh memakai path yang mirip, tetapi artinya berbeda total.

Contoh semantik pada skincare API:

Contoh method dan niatSalin
GET    /v1/products                 # baca daftar produk
GET    /v1/products/prd_001          # baca detail produk
POST   /v1/cart/items                # tambah item baru ke cart
PATCH  /v1/cart/items/item_123       # ubah quantity item cart
DELETE /v1/cart/items/item_123       # hapus item dari cart
POST   /v1/orders                    # buat order dari cart
POST   /v1/payment/webhooks/xendit   # terima event dari payment gateway

Status code adalah sinyal ringkas untuk client, log, monitoring, dan manusia yang membaca response.

Kamu tidak perlu menghafal semua status code. Untuk backend API sehari-hari, ada sekumpulan kecil yang harus konsisten dipakai. Konsistensi lebih penting daripada variasi yang terlalu kreatif.

Diagram berikut membantu memilih status code yang tepat untuk setiap kondisi di Go handler:

flowchart TD
  REQ([Request masuk]) --> AUTH{Autentikasi valid}
  AUTH -->|tidak| C401[401 Unauthorized]
  AUTH -->|ya| PERM{Punya izin}
  PERM -->|tidak| C403[403 Forbidden]
  PERM -->|ya| FOUND{Resource ada}
  FOUND -->|tidak| C404[404 Not Found]
  FOUND -->|ya| VALID{Input valid}
  VALID -->|JSON rusak| C400[400 Bad Request]
  VALID -->|aturan bisnis gagal| C422[422 Unprocessable]
  VALID -->|ok| EXEC{Eksekusi berhasil}
  EXEC -->|konflik state| C409[409 Conflict]
  EXEC -->|error tak terduga| C500[500 Server Error]
  EXEC -->|resource dibuat| C201[201 Created]
  EXEC -->|data dikembalikan| C200[200 OK]

Gambar 1. Pohon keputusan pemilihan status code HTTP di setiap Go handler.

Header adalah metadata request dan response. Ia tidak membawa data domain utama, tetapi sangat penting untuk parsing, keamanan, tracing, dan cache.

Header paling sering kamu sentuh di API backend adalah Content-Type, Authorization, dan X-Request-ID.

Header request checkoutSalin
POST /v1/orders HTTP/1.1
Host: api.skincare.local
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
X-Request-ID: req_checkout_20260606_0001

Header response checkoutSalin
HTTP/1.1 201 Created
Content-Type: application/json
X-Request-ID: req_checkout_20260606_0001

Dalam Go, header adalah map khusus bernama http.Header. Ia case-insensitive secara semantik, tetapi tetap gunakan nama standar agar mudah dibaca. Untuk response JSON, set Content-Type sebelum menulis body.

internal/httpjson/response.goSalin
package httpjson

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

func WriteJSON(w http.ResponseWriter, status int, payload any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(payload)
}

Tidak semua data request harus masuk ke tempat yang sama. Path, query, header, dan body punya peran berbeda.

Gunakan path parameter untuk identitas resource. Gunakan query parameter untuk filter, sort, search, dan pagination. Gunakan body untuk payload yang kompleks, terutama saat membuat atau mengubah data.

Path, query, dan bodySalin
GET /v1/products/prd_001
# prd_001 adalah path parameter, identitas produk

GET /v1/products?skin_type=oily&sort=price_asc&page=1
# skin_type, sort, dan page adalah query parameter

POST /v1/cart/items
# payload item dikirim di body JSON

request body POST /v1/cart/itemsSalin
{
  "product_id": "prd_001",
  "quantity": 2
}

JSON API yang baik bukan hanya valid JSON, tetapi juga konsisten dalam bentuk response sukses dan gagal.

Di React, konsistensi response membuat hook lebih sederhana. Di backend Go, konsistensi response membuat handler lebih mudah dites, error lebih mudah dipetakan, dan dokumentasi API lebih mudah ditulis.

response sukses GET /v1/products/prd_001Salin
{
  "data": {
    "id": "prd_001",
    "name": "Niacinamide Serum",
    "slug": "niacinamide-serum",
    "price": 129000,
    "stock": 42,
    "skin_types": ["oily", "combination"]
  }
}

response list dengan metadataSalin
{
  "data": [
    { "id": "prd_001", "name": "Niacinamide Serum", "price": 129000 },
    { "id": "prd_002", "name": "Gentle Cleanser", "price": 99000 }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 84
  }
}

response error validasiSalin
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "quantity must be at least 1",
    "fields": {
      "quantity": "must be greater than 0"
    }
  }
}

Pada modul berikutnya, kita akan mulai menulis helper writeJSON dan readJSON agar semua handler memakai format yang sama. Jangan biarkan tiap handler menulis bentuk error sendiri-sendiri.

Berikut peta awal endpoint yang akan menjadi tulang punggung online shop skincare kita.

Endpoint di atas belum membahas autentikasi, otorisasi, transaksi database, dan validasi penuh. Itu akan datang bertahap. Tujuan chapter ini adalah membaca endpoint sebagai kontrak HTTP yang jelas.

Satu request API yang terlihat sederhana biasanya melewati beberapa lapisan sebelum menghasilkan response.

sequenceDiagram
  autonumber
  participant FE as React Frontend
  participant API as Go API
  participant MW as Middleware
  participant H as Handler
  participant S as Service
  participant R as Repository pgx
  participant DB as PostgreSQL
  FE->>API: POST /v1/orders JSON
  API->>MW: request masuk
  MW->>MW: request id, logging, auth
  MW->>H: teruskan request
  H->>H: decode JSON dan validasi bentuk awal
  H->>S: CreateOrder(ctx, input)
  S->>S: cek aturan bisnis checkout
  S->>R: reserve stock dan insert order
  R->>DB: SQL transaction
  DB-->>R: rows affected dan order id
  R-->>S: result atau error
  S-->>H: order baru
  H-->>FE: 201 Created JSON

Gambar 2. Alur request checkout dari React frontend ke Go API sampai PostgreSQL.

Bagian pentingnya adalah setiap lapisan punya tanggung jawab berbeda. Handler memahami HTTP. Service memahami bisnis. Repository memahami database. HTTP status diputuskan di tepi API, tetapi penyebabnya biasanya berasal dari validasi, aturan bisnis, atau database.

Kita mulai dari net/http agar kamu melihat bentuk asli HTTP server Go sebelum chi masuk di chapter berikutnya.

Sejak Go 1.22, http.ServeMux mendukung pattern method dan path secara langsung. Ini cukup untuk contoh kecil. Pada proyek besar, kita akan memakai chi karena grouping route, middleware chain, dan path parameter lebih nyaman.

cmd/api/main.goSalin
package main

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

type productResponse struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	PriceRupiah int64  `json:"price"`
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /v1/health", healthHandler)
	mux.HandleFunc("GET /v1/products", listProductsHandler)

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           requestID(mux),
		ReadHeaderTimeout: 5 * time.Second,
	}

	slog.Info("api server listening", "addr", srv.Addr)
	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		slog.Error("server stopped", "error", err)
	}
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}

func listProductsHandler(w http.ResponseWriter, r *http.Request) {
	skinType := r.URL.Query().Get("skin_type")
	_ = skinType

	products := []productResponse{
		{ID: "prd_001", Name: "Niacinamide Serum", PriceRupiah: 129000},
		{ID: "prd_002", Name: "Gentle Cleanser", PriceRupiah: 99000},
	}

	writeJSON(w, http.StatusOK, map[string]any{
		"data": products,
		"meta": map[string]any{"page": 1, "page_size": 20},
	})
}

func writeJSON(w http.ResponseWriter, status int, payload any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	if err := json.NewEncoder(w).Encode(payload); err != nil {
		slog.Error("encode response", "error", err)
	}
}

func requestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := r.Header.Get("X-Request-ID")
		if id == "" {
			id = fmt.Sprintf("req_%x", time.Now().UnixNano())
		}
		w.Header().Set("X-Request-ID", id)
		next.ServeHTTP(w, r)
	})
}

TerminalSalin
go mod init github.com/kamu/skincare-backend
go run ./cmd/api

TerminalSalin
curl -i http://localhost:8080/v1/health
curl -i "http://localhost:8080/v1/products?skin_type=oily&page=1"

HTTP terlihat sederhana, tetapi banyak bug backend lahir dari salah menafsirkan detail kecil.

HTTP adalah fondasi semua chapter di Roadmap 2, dari handler net/http, routing chi, middleware, validasi, sampai testing API.

Langkah berikutnya adalah masuk ke net/http lebih serius. Kita akan membedah http.Handler, http.ResponseWriter, *http.Request, helper JSON, timeout server, dan cara menyusun handler yang siap dipindahkan ke chi.