Desain REST API E-Commerce
Skincare yang Utuh

Kontrak yang dipakai storefront, admin, dan payment provider

REST API adalah kontrak jangka panjang yang dipakai frontend React, mobile app, admin dashboard, dan payment provider untuk berbicara dengan backend. Ini chapter di mana semua potongan Roadmap 2 berkumpul.

Enam modul terakhir membangun satu proyek menerus: backend online shop skincare. Kamu sudah punya handler net/http, routing chi, envelope respons httpx, middleware, validasi, dan autentikasi JWT. Modul ini tidak memperkenalkan banyak konsep baru, melainkan merakit semuanya menjadi satu peta API yang utuh dan menjawab pertanyaan desain yang sebenarnya: resource apa yang kita ekspos, dan bagaimana client memahaminya.

Di React, kamu sering mulai dari kebutuhan layar: halaman katalog butuh data produk, halaman cart butuh item, halaman checkout butuh order. Di backend, kita membalik sudut pandang itu menjadi resource dan aksi HTTP yang stabil. Endpoint tidak dinamai mengikuti function internal, melainkan mengikuti cara client memahami bisnis online shop.

Di Laravel kamu terbiasa dengan resource controller dan route group. Di Go dengan net/http dan chi, ide besarnya sama, tetapi semuanya lebih eksplisit: handler menerima http.ResponseWriter dan *http.Request, router menyusun method dan path, middleware adalah function yang membungkus http.Handler.

Permukaan API Roadmap 2 mencakup katalog produk publik, autentikasi, cart customer, checkout, riwayat order, admin product management, dan webhook pembayaran. Database, transaksi, dan repository pgx diperdalam di Roadmap 3, tetapi bentuk API harus sudah jelas dan benar sejak sekarang, karena kontrak inilah yang akan dipakai frontend untuk mulai bekerja paralel.

Bukan sekadar JSON di atas HTTP

REST yang baik membuat resource mudah ditebak, aman dikonsumsi, dan tahan terhadap retry. Untuk e-commerce, beberapa prinsip ini menentukan apakah uang dan stok tetap konsisten.

Selain itu, ada empat properti khusus e-commerce yang wajib dipikirkan sejak desain, bukan ditambal belakangan.

Tiga lapis akses: publik, customer, admin, plus webhook

Inilah peta kanonik permukaan API skincare. Semua modul Roadmap 2 mengarah ke sini, dan Roadmap 3 sampai 5 akan mengisinya dengan implementasi nyata.

Publik (tanpa autentikasi)

Customer (butuh login)

Admin (butuh role admin)

flowchart TD
  subgraph Clients
    FE["React storefront"]
    ADM["Admin dashboard"]
    PSP["Payment provider"]
  end
  FE -->|catalog| API
  FE -->|login & cart & checkout| API
  ADM -->|kelola produk| API
  PSP -->|webhook signed| API
  API["chi router /v1"] --> PUB["Publik<br/>products, auth, webhook"]
  API --> CUST["Customer (auth)<br/>cart, checkout, orders"]
  API --> ADMG["Admin (RequireRole admin)<br/>admin/products"]
  PUB --> SVC["Service layer (Roadmap 4)"]
  CUST --> SVC
  ADMG --> SVC
  SVC --> DB[("PostgreSQL (Roadmap 3)")]

Gambar 1. Permukaan API dibagi tiga grup akses plus webhook publik. Pembagian ini akan kita wujudkan langsung sebagai grup middleware di router chi.

Tipe inti yang dipakai lintas seluruh permukaan API

Sebelum menulis handler, kunci dulu model domainnya. Konsistensi tipe inilah yang membuat enam modul terasa seperti satu proyek, bukan enam latihan terpisah.

Uang disimpan sebagai integer rupiah, bukan float64. Field PriceRupiah int64 dengan JSON tag price menghindari galat pembulatan yang khas pada tipe pecahan. Total order memakai TotalRupiah int64 dengan JSON tag total. Ini konvensi yang sama persis di seluruh proyek.

internal/product/model.goSalin
package product

type Product struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Slug        string `json:"slug"`
	Category    string `json:"category"`
	PriceRupiah int64  `json:"price"`
	Stock       int    `json:"stock"`
	Description string `json:"description,omitempty"`
	Status      string `json:"status"` // draft, active, archived
}

internal/cart/model.goSalin
package cart

type CartItem struct {
	ID          int64 `json:"id"`
	ProductID   int64 `json:"product_id"`
	Name        string `json:"name"`
	Quantity    int    `json:"quantity"`
	PriceRupiah int64  `json:"price"`     // harga satuan saat ditambahkan
	Subtotal    int64  `json:"subtotal"`  // PriceRupiah * Quantity
}

internal/order/model.goSalin
package order

import "time"

type Order struct {
	ID          int64       `json:"id"`
	Items       []OrderItem `json:"items"`
	TotalRupiah int64       `json:"total"`
	Status      string      `json:"status"` // pending, paid, shipped, cancelled
	CreatedAt   time.Time   `json:"created_at"`
}

type OrderItem struct {
	ProductID   int64  `json:"product_id"`
	Name        string `json:"name"`        // dibekukan saat checkout
	Quantity    int    `json:"quantity"`
	PriceRupiah int64  `json:"price"`       // dibekukan saat checkout
	Subtotal    int64  `json:"subtotal"`
}

internal/user/model.goSalin
package user

type User struct {
	ID           int64  `json:"id"`
	Email        string `json:"email"`
	Role         string `json:"role"`  // customer, admin
	PasswordHash string `json:"-"`     // JANGAN pernah keluar ke client
}

Untuk response yang dibaca client, kita memakai envelope httpx yang sudah dirancang di modul Request & Response. Itu kontrak yang tidak diulang di sini, hanya dipakai.

internal/httpx/response.go (ringkasan kontrak dari modul Request & Response)Salin
package httpx

// Meta menemani response list (pagination).
type Meta struct {
	Page       int   `json:"page"`
	PerPage    int   `json:"per_page"`
	Total      int64 `json:"total"`
	TotalPages int   `json:"total_pages"`
}

// FieldError dipakai oleh hasil validasi.
type FieldError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

func JSON(w http.ResponseWriter, status int, payload any)            // encode + set header
func Data(w http.ResponseWriter, status int, data any)               // {"data": ...}
func List(w http.ResponseWriter, status int, data any, meta Meta)    // {"data": ..., "meta": ...}
func Error(w http.ResponseWriter, status int, code, message string)  // {"error": {code, message}}
func ValidationFailed(w http.ResponseWriter, fields []FieldError)    // 422 validation_error

Modular monolith kecil, dipecah per domain

Di akhir Roadmap 2, struktur folder sudah menyerupai modular monolith. Setiap domain punya package sendiri yang mengumpulkan handler, request, dan response yang berubah bersama.

Package dipisah per domain (product, cart, order), bukan per layer global (controllers/, services/, models/). Di Go, package yang sehat mengumpulkan hal yang berubah bersama. Saat kontrak katalog berubah, product/handler.go, product/request.go, dan product/response.go cenderung berubah bareng, jadi enak kalau bertetangga.

Router final memetakan langsung tiga lapis akses dari peta endpoint ke tiga konstruksi chi: route biasa untuk publik, satu r.Group dengan Authenticate untuk customer, dan satu r.Route("/admin") dengan Authenticate plus RequireRole("admin") untuk admin.

flowchart TD
  ROOT["chi.NewRouter()"] --> GLOBAL["Global middleware<br/>RequestID, Logger, Recoverer, Timeout"]
  GLOBAL --> V1["Route /v1"]
  V1 --> P1["GET /products, /products/{id}"]
  V1 --> P2["POST /auth/register, /login, /refresh"]
  V1 --> P3["POST /payments/webhook"]
  V1 --> GAUTH["Group: Use(auth.Authenticate)"]
  GAUTH --> C1["GET /cart, cart/items..."]
  GAUTH --> C2["POST /checkout, GET /orders..."]
  V1 --> GADMIN["Route /admin:<br/>Use(Authenticate), Use(RequireRole admin)"]
  GADMIN --> A1["POST/PUT/PATCH/DELETE /products..."]

Gambar 2. Arsitektur router. Publik, customer, dan admin bukan sekadar konvensi path, tetapi grup middleware yang nyata dan terlihat di kode.

Endpoint paling sering dibaca, jadi kontraknya harus paling stabil

Katalog adalah endpoint yang paling sering dipanggil. Desain query dan pagination-nya menentukan apakah frontend bisa membangun halaman list yang nyaman tanpa menebak.

Query list harus mencerminkan kebutuhan UI (filter kategori, kata kunci, rentang harga, sort, halaman), bukan membuka semua kolom database mentah-mentah. Kita parse query ke struct, beri default yang aman, dan batasi per_page agar tidak ada yang meminta sejuta baris sekaligus.

internal/product/request.goSalin
package product

import (
	"net/http"
	"strconv"
	"strings"
)

type ListQuery struct {
	Category string
	Search   string
	MinPrice int64
	MaxPrice int64
	Sort     string
	Page     int
	PerPage  int
}

func ParseListQuery(r *http.Request) ListQuery {
	q := r.URL.Query()

	lq := ListQuery{
		Category: strings.TrimSpace(q.Get("category")),
		Search:   strings.TrimSpace(q.Get("q")),
		MinPrice: int64FromQuery(q.Get("min_price"), 0),
		MaxPrice: int64FromQuery(q.Get("max_price"), 0),
		Sort:     q.Get("sort"),
		Page:     intFromQuery(q.Get("page"), 1),
		PerPage:  intFromQuery(q.Get("per_page"), 20),
	}

	if lq.Page < 1 {
		lq.Page = 1
	}
	if lq.PerPage < 1 || lq.PerPage > 100 {
		lq.PerPage = 20
	}
	if !allowedSort(lq.Sort) {
		lq.Sort = "newest"
	}
	return lq
}

// allowedSort memakai allowlist, bukan nama kolom bebas dari client.
func allowedSort(sort string) bool {
	switch sort {
	case "", "newest", "price_asc", "price_desc", "name_asc":
		return true
	default:
		return false
	}
}

func intFromQuery(value string, fallback int) int {
	if value == "" {
		return fallback
	}
	n, err := strconv.Atoi(value)
	if err != nil {
		return fallback
	}
	return n
}

func int64FromQuery(value string, fallback int64) int64 {
	if value == "" {
		return fallback
	}
	n, err := strconv.ParseInt(value, 10, 64)
	if err != nil {
		return fallback
	}
	return n
}

Handler list memanggil service, lalu membungkus hasil dengan httpx.List agar response membawa data dan meta pagination. Detail produk yang tidak ditemukan membalas 404 dengan kode product_not_found, bukan 500.

internal/product/handler.goSalin
package product

import (
	"errors"
	"net/http"

	"github.com/go-chi/chi/v5"

	"github.com/kamu/skincare-backend/internal/httpx"
)

type Handler struct {
	service Service
}

type Service interface {
	List(ctx context.Context, q ListQuery) (items []Product, total int64, err error)
	GetByID(ctx context.Context, id int64) (Product, error)
}

var ErrProductNotFound = errors.New("product not found")

func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
	q := ParseListQuery(r)

	items, total, err := h.service.List(r.Context(), q)
	if err != nil {
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal memuat produk")
		return
	}

	meta := httpx.NewMeta(q.Page, q.PerPage, total)
	httpx.List(w, http.StatusOK, toResponses(items), meta)
}

func (h *Handler) Detail(w http.ResponseWriter, r *http.Request) {
	id, err := parseID(chi.URLParam(r, "id"))
	if err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "id produk harus angka positif")
		return
	}

	product, err := h.service.GetByID(r.Context(), id)
	if errors.Is(err, ErrProductNotFound) {
		httpx.Error(w, http.StatusNotFound, "product_not_found", "produk tidak ditemukan")
		return
	}
	if err != nil {
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal memuat produk")
		return
	}

	httpx.Data(w, http.StatusOK, toDetailResponse(product))
}

Milik user yang login, bukan dikirim dari client

Cart adalah resource milik user yang sedang login. Identitas user diambil dari token, bukan dari body request, sehingga endpoint cart tidak pernah menerima user_id dari client.

Perhatikan: cart/items/{id} merujuk ID item cart, bukan ID produk. Satu item cart punya metadata sendiri (quantity, harga saat dimasukkan, kelak varian), sehingga ia layak jadi resource tersendiri yang bisa di-PATCH dan di-DELETE.

Validasi memakai pola yang sudah kita sepakati di modul Validasi: hasil validasi adalah []httpx.FieldError, lalu dibalas dengan httpx.ValidationFailed (HTTP 422, kode validation_error). Validasi manual eksplisit di boundary handler, sadar akan zero value Go.

internal/cart/request.goSalin
package cart

import "github.com/kamu/skincare-backend/internal/httpx"

type AddItemRequest struct {
	ProductID int64 `json:"product_id"`
	Quantity  int   `json:"quantity"`
}

type UpdateItemRequest struct {
	Quantity int `json:"quantity"`
}

func (r AddItemRequest) Validate() []httpx.FieldError {
	var fields []httpx.FieldError
	if r.ProductID <= 0 {
		fields = append(fields, httpx.FieldError{Field: "product_id", Message: "product_id wajib diisi"})
	}
	if r.Quantity < 1 {
		fields = append(fields, httpx.FieldError{Field: "quantity", Message: "quantity minimal 1"})
	}
	return fields
}

func (r UpdateItemRequest) Validate() []httpx.FieldError {
	var fields []httpx.FieldError
	if r.Quantity < 1 {
		fields = append(fields, httpx.FieldError{Field: "quantity", Message: "quantity minimal 1"})
	}
	return fields
}

internal/cart/handler.goSalin
package cart

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

	"github.com/go-chi/chi/v5"

	"github.com/kamu/skincare-backend/internal/auth"
	"github.com/kamu/skincare-backend/internal/httpx"
)

type Handler struct {
	service Service
}

func (h *Handler) AddItem(w http.ResponseWriter, r *http.Request) {
	claims, ok := auth.UserFrom(r.Context())
	if !ok {
		httpx.Error(w, http.StatusUnauthorized, "unauthorized", "silakan login dulu")
		return
	}

	var req AddItemRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "body bukan JSON yang valid")
		return
	}
	if fields := req.Validate(); len(fields) > 0 {
		httpx.ValidationFailed(w, fields)
		return
	}

	cart, err := h.service.AddItem(r.Context(), claims.UserID, req)
	if errors.Is(err, ErrProductNotFound) {
		httpx.Error(w, http.StatusNotFound, "product_not_found", "produk tidak ditemukan")
		return
	}
	if err != nil {
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal menambah item")
		return
	}

	httpx.Data(w, http.StatusCreated, toCartResponse(cart))
}

func (h *Handler) UpdateItem(w http.ResponseWriter, r *http.Request) {
	claims, ok := auth.UserFrom(r.Context())
	if !ok {
		httpx.Error(w, http.StatusUnauthorized, "unauthorized", "silakan login dulu")
		return
	}

	itemID, err := parseID(chi.URLParam(r, "id"))
	if err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "id item harus angka positif")
		return
	}

	var req UpdateItemRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "body bukan JSON yang valid")
		return
	}
	if fields := req.Validate(); len(fields) > 0 {
		httpx.ValidationFailed(w, fields)
		return
	}

	cart, err := h.service.UpdateItem(r.Context(), claims.UserID, itemID, req)
	if errors.Is(err, ErrItemNotFound) {
		httpx.Error(w, http.StatusNotFound, "not_found", "item cart tidak ditemukan")
		return
	}
	if err != nil {
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal mengubah item")
		return
	}

	httpx.Data(w, http.StatusOK, toCartResponse(cart))
}

Batas antara belanja dan transaksi bisnis

Checkout adalah momen di mana cart berubah menjadi order. Ini titik paling rawan di seluruh API: ia menyentuh stok, harga, dan uang, jadi harus idempotent dan konsisten.

Body checkout tidak perlu mengirim seluruh item, karena sumber kebenaran cart ada di server. Client cukup mengirim alamat pengiriman, metode pengiriman, metode pembayaran, dan satu idempotency_key yang ia bangkitkan sendiri (misalnya UUID per percobaan checkout).

internal/order/request.goSalin
package order

import "github.com/kamu/skincare-backend/internal/httpx"

type CheckoutRequest struct {
	ShippingAddressID int64  `json:"shipping_address_id"`
	ShippingMethod    string `json:"shipping_method"`
	PaymentMethod     string `json:"payment_method"`
	IdempotencyKey    string `json:"idempotency_key"`
}

func (r CheckoutRequest) Validate() []httpx.FieldError {
	var fields []httpx.FieldError
	if r.ShippingAddressID <= 0 {
		fields = append(fields, httpx.FieldError{Field: "shipping_address_id", Message: "alamat pengiriman wajib dipilih"})
	}
	if r.ShippingMethod == "" {
		fields = append(fields, httpx.FieldError{Field: "shipping_method", Message: "metode pengiriman wajib diisi"})
	}
	if r.PaymentMethod == "" {
		fields = append(fields, httpx.FieldError{Field: "payment_method", Message: "metode pembayaran wajib diisi"})
	}
	if r.IdempotencyKey == "" {
		fields = append(fields, httpx.FieldError{Field: "idempotency_key", Message: "idempotency_key wajib diisi"})
	}
	return fields
}

Diagram berikut menunjukkan alur checkout end-to-end. Di Roadmap 2 service masih in-memory, tetapi bentuk langkahnya sudah final. Di Roadmap 3, langkah validasi cart sampai insert order akan dibungkus satu transaksi database.

sequenceDiagram
  participant FE as React Client
  participant API as chi Handler
  participant SVC as Order Service
  participant DB as Store (pgx di Roadmap 3)
  participant PSP as Payment Provider
  FE->>API: POST /v1/checkout (+ idempotency_key)
  API->>SVC: Checkout(userID, req)
  SVC->>DB: Cek idempotency_key
  alt key sudah pernah dipakai
    DB-->>SVC: Order lama
    SVC-->>API: Order yang sama
    API-->>FE: 200 OK (order existing)
  else key baru
    SVC->>DB: Validasi cart & reserve stok
    SVC->>DB: Insert order + order_items (harga dibekukan)
    SVC->>PSP: Buat payment intent
    PSP-->>SVC: payment_url
    SVC-->>API: Order baru (status pending)
    API-->>FE: 201 Created
  end

Gambar 3. Idempotensi checkout: request dengan idempotency_key yang sama mengembalikan order yang sama, bukan membuat order kedua.

Handler checkout merakit semua lapis: ambil user dari context, decode dan validasi body, panggil service, lalu pilih status code yang jujur. Order yang baru dibuat membalas 201, sedangkan idempotency hit membalas 200 dengan order yang sudah ada.

internal/order/handler.goSalin
package order

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

	"github.com/kamu/skincare-backend/internal/auth"
	"github.com/kamu/skincare-backend/internal/httpx"
)

var (
	ErrCartEmpty     = errors.New("cart kosong")
	ErrStockNotEnough = errors.New("stok tidak cukup")
)

func (h *Handler) Checkout(w http.ResponseWriter, r *http.Request) {
	claims, ok := auth.UserFrom(r.Context())
	if !ok {
		httpx.Error(w, http.StatusUnauthorized, "unauthorized", "silakan login dulu")
		return
	}

	var req CheckoutRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "body bukan JSON yang valid")
		return
	}
	if fields := req.Validate(); len(fields) > 0 {
		httpx.ValidationFailed(w, fields)
		return
	}

	order, created, err := h.service.Checkout(r.Context(), claims.UserID, req)
	switch {
	case errors.Is(err, ErrCartEmpty):
		httpx.Error(w, http.StatusConflict, "conflict", "cart kosong, tidak bisa checkout")
		return
	case errors.Is(err, ErrStockNotEnough):
		httpx.Error(w, http.StatusConflict, "conflict", "stok salah satu produk tidak mencukupi")
		return
	case err != nil:
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal memproses checkout")
		return
	}

	status := http.StatusOK
	if created {
		status = http.StatusCreated
	}
	httpx.Data(w, status, toOrderResponse(order))
}

Status order berpindah mengikuti state machine yang eksplisit. Bukan field bebas, melainkan transisi yang punya aturan.

stateDiagram-v2
  [*] --> pending: checkout berhasil
  pending --> paid: webhook payment.paid
  pending --> cancelled: timeout bayar / dibatalkan
  paid --> shipped: admin kirim
  paid --> cancelled: refund sebelum kirim
  shipped --> [*]
  cancelled --> [*]
  note right of pending: Hanya transisi sah yang diizinkan.<br/>cancelled tidak bisa kembali ke pending.

Gambar 4. State machine order. Service menolak transisi tidak sah (misalnya shipped langsung ke pending), sehingga status tidak bisa korup.

Route, validasi, dan role guard yang lebih ketat

Admin API memodifikasi katalog, jadi route-nya terpisah dan dilindungi RequireRole("admin"). Kebutuhan admin berbeda dari storefront, sehingga endpoint-nya pun berbeda.

PUT mengganti seluruh resource, jadi setiap field wajib dikirim. PATCH mengubah sebagian, jadi field opsional. Di Go, membedakan “field tidak dikirim” dari “field dikirim bernilai kosong” penting, dan kita memakai pointer untuk itu pada DTO patch.

internal/product/request.go (admin)Salin
package product

import (
	"unicode/utf8"

	"github.com/kamu/skincare-backend/internal/httpx"
)

// CreateProductRequest dipakai POST dan PUT (semua field wajib).
type CreateProductRequest struct {
	Name        string `json:"name"`
	Category    string `json:"category"`
	PriceRupiah int64  `json:"price"`
	Stock       int    `json:"stock"`
	Description string `json:"description"`
	Status      string `json:"status"`
}

func (r CreateProductRequest) Validate() []httpx.FieldError {
	var fields []httpx.FieldError
	if utf8.RuneCountInString(r.Name) < 3 {
		fields = append(fields, httpx.FieldError{Field: "name", Message: "nama minimal 3 karakter"})
	}
	if r.Category == "" {
		fields = append(fields, httpx.FieldError{Field: "category", Message: "kategori wajib diisi"})
	}
	if r.PriceRupiah <= 0 {
		fields = append(fields, httpx.FieldError{Field: "price", Message: "harga harus lebih dari 0"})
	}
	if r.Stock < 0 {
		fields = append(fields, httpx.FieldError{Field: "stock", Message: "stok tidak boleh negatif"})
	}
	if !allowedStatus(r.Status) {
		fields = append(fields, httpx.FieldError{Field: "status", Message: "status harus draft, active, atau archived"})
	}
	return fields
}

// PatchProductRequest dipakai PATCH. Pointer nil berarti "tidak diubah".
type PatchProductRequest struct {
	Name        *string `json:"name"`
	Category    *string `json:"category"`
	PriceRupiah *int64  `json:"price"`
	Stock       *int    `json:"stock"`
	Status      *string `json:"status"`
}

func (r PatchProductRequest) Validate() []httpx.FieldError {
	var fields []httpx.FieldError
	if r.Name != nil && utf8.RuneCountInString(*r.Name) < 3 {
		fields = append(fields, httpx.FieldError{Field: "name", Message: "nama minimal 3 karakter"})
	}
	if r.PriceRupiah != nil && *r.PriceRupiah <= 0 {
		fields = append(fields, httpx.FieldError{Field: "price", Message: "harga harus lebih dari 0"})
	}
	if r.Status != nil && !allowedStatus(*r.Status) {
		fields = append(fields, httpx.FieldError{Field: "status", Message: "status harus draft, active, atau archived"})
	}
	return fields
}

func allowedStatus(status string) bool {
	switch status {
	case "draft", "active", "archived":
		return true
	default:
		return false
	}
}

Request dari sistem lain, bukan dari user yang login

Webhook adalah panggilan dari payment provider ke API kita. Ia publik (tidak memakai JWT customer), tetapi tetap harus diverifikasi dan diproses idempotent.

Tiga aturan webhook pembayaran: verifikasi signature dari raw body (bukan JSON yang sudah di-decode ulang), proses idempotent berdasarkan event ID, dan balas 200 secepat mungkin agar provider tidak menganggap gagal lalu retry berlebihan.

sequenceDiagram
  participant PSP as Payment Provider
  participant API as Webhook Handler
  participant SVC as Payment Service
  participant DB as Store
  PSP->>API: POST /v1/payments/webhook (+ signature)
  API->>API: Baca raw body, verifikasi signature HMAC
  alt signature invalid
    API-->>PSP: 401 unauthorized
  else valid
    API->>SVC: Handle(event)
    SVC->>DB: Sudah pernah proses event.ID?
    alt sudah
      DB-->>SVC: ya
      SVC-->>API: no-op (idempotent)
      API-->>PSP: 200 OK
    else belum
      SVC->>DB: Tandai event diproses
      SVC->>DB: Order -> paid
      SVC-->>API: ok
      API-->>PSP: 200 OK
    end
  end

Gambar 5. Webhook harus tahan retry. Provider bisa mengirim event yang sama beberapa kali, dan kita hanya boleh memproses efeknya sekali.

internal/payment/webhook.goSalin
package payment

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"

	"github.com/kamu/skincare-backend/internal/httpx"
)

type WebhookHandler struct {
	service Service
	secret  []byte
}

type Event struct {
	ID      string `json:"id"`
	Type    string `json:"type"`     // payment.paid, payment.failed
	OrderID int64  `json:"order_id"`
}

func (h *WebhookHandler) Handle(w http.ResponseWriter, r *http.Request) {
	// Batasi ukuran body webhook agar provider nakal tidak membanjiri kita.
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20)

	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "gagal membaca body")
		return
	}

	if !verifySignature(r.Header.Get("X-Signature"), rawBody, h.secret) {
		httpx.Error(w, http.StatusUnauthorized, "unauthorized", "signature tidak valid")
		return
	}

	var event Event
	if err := json.Unmarshal(rawBody, &event); err != nil {
		httpx.Error(w, http.StatusBadRequest, "invalid_json", "body bukan event yang valid")
		return
	}

	// HandleEvent idempotent: cek event.ID sebelum mengubah status order.
	if err := h.service.HandleEvent(r.Context(), event); err != nil {
		httpx.Error(w, http.StatusInternalServerError, "internal_error", "gagal memproses event")
		return
	}

	httpx.JSON(w, http.StatusOK, map[string]string{"status": "ok"})
}

// verifySignature membandingkan HMAC-SHA256 raw body dengan header signature.
// hmac.Equal memakai perbandingan constant-time agar aman dari timing attack.
func verifySignature(signature string, body, secret []byte) bool {
	if signature == "" {
		return false
	}
	mac := hmac.New(sha256.New, secret)
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

Tiga lapis akses menjadi tiga konstruksi chi

Sekarang semua bertemu. Router chi menyusun publik, customer, dan admin sebagai grup middleware yang nyata, dan menyambungkan setiap domain ke peta endpoint.

Package net/http tetap fondasinya. chi (github.com/go-chi/chi/v5) kompatibel dengan http.Handler, jadi route tetap idiomatik Go, bukan framework tertutup. Middleware umum dipasang sekali di atas, lalu auth dan role guard dipasang per grup.

internal/router/router.goSalin
package router

import (
	"net/http"
	"time"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"

	"github.com/kamu/skincare-backend/internal/auth"
	"github.com/kamu/skincare-backend/internal/cart"
	"github.com/kamu/skincare-backend/internal/order"
	"github.com/kamu/skincare-backend/internal/payment"
	"github.com/kamu/skincare-backend/internal/product"
)

type Handlers struct {
	Auth    *auth.Handler
	Product *product.Handler
	Cart    *cart.Handler
	Order   *order.Handler
	Webhook *payment.WebhookHandler
}

func New(h Handlers) http.Handler {
	r := chi.NewRouter()

	// Middleware global, dipasang sekali untuk semua route.
	r.Use(middleware.RequestID)
	r.Use(middleware.Logger)
	r.Use(middleware.Recoverer)
	r.Use(middleware.Timeout(15 * time.Second))

	r.Get("/healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
	})

	r.Route("/v1", func(r chi.Router) {
		// --- Publik ---
		r.Get("/products", h.Product.List)
		r.Get("/products/{id}", h.Product.Detail)
		r.Post("/auth/register", h.Auth.Register)
		r.Post("/auth/login", h.Auth.Login)
		r.Post("/auth/refresh", h.Auth.Refresh)
		r.Post("/payments/webhook", h.Webhook.Handle)

		// --- Customer (butuh login) ---
		r.Group(func(r chi.Router) {
			r.Use(auth.Authenticate)

			r.Get("/cart", h.Cart.Get)
			r.Post("/cart/items", h.Cart.AddItem)
			r.Patch("/cart/items/{id}", h.Cart.UpdateItem)
			r.Delete("/cart/items/{id}", h.Cart.DeleteItem)

			r.Post("/checkout", h.Order.Checkout)
			r.Get("/orders", h.Order.ListMine)
			r.Get("/orders/{id}", h.Order.DetailMine)
		})

		// --- Admin (butuh role admin) ---
		r.Route("/admin", func(r chi.Router) {
			r.Use(auth.Authenticate)
			r.Use(auth.RequireRole("admin"))

			r.Post("/products", h.Product.AdminCreate)
			r.Put("/products/{id}", h.Product.AdminReplace)
			r.Patch("/products/{id}", h.Product.AdminPatch)
			r.Delete("/products/{id}", h.Product.AdminArchive)
		})
	})

	return r
}

Middleware Authenticate membaca header Authorization: Bearer ..., memverifikasi token, lalu menaruh *Claims di context. Handler mengambilnya lewat auth.UserFrom. Inilah perekat antara modul Auth dan permukaan API ini.

internal/auth/middleware.go (ringkasan dari modul Autentikasi)Salin
package auth

import (
	"net/http"
	"strings"

	"github.com/kamu/skincare-backend/internal/httpx"
)

func Authenticate(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		raw := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
		claims, err := ParseToken(raw)
		if err != nil {
			httpx.Error(w, http.StatusUnauthorized, "unauthorized", "token tidak valid")
			return
		}
		ctx := withClaims(r.Context(), claims)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

func RequireRole(role string) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			claims, ok := UserFrom(r.Context())
			if !ok {
				httpx.Error(w, http.StatusUnauthorized, "unauthorized", "silakan login dulu")
				return
			}
			if claims.Role != role {
				httpx.Error(w, http.StatusForbidden, "forbidden", "akses ditolak")
				return
			}
			next.ServeHTTP(w, r)
		})
	}
}

Route bisa diuji walau service masih in-memory

Latihan ini membuat peta route hidup walau service dan database masih dummy. Tujuannya: frontend dan backend bisa menyepakati kontrak lebih awal.

cmd/api/main.goSalin
package main

import (
	"log/slog"
	"net/http"
	"os"

	"github.com/kamu/skincare-backend/internal/router"
)

func main() {
	// Di proyek nyata, handler diisi service + repository.
	// Untuk peta route, handler stub sudah cukup.
	h := router.Handlers{}

	srv := router.New(h)

	addr := ":8080"
	slog.Info("server listening", "addr", addr)
	if err := http.ListenAndServe(addr, srv); err != nil {
		slog.Error("server stopped", "error", err)
		os.Exit(1)
	}
}

TerminalSalin
go mod init github.com/kamu/skincare-backend
go get github.com/go-chi/chi/v5@v5.3.0
go mod tidy
go run ./cmd/api

Uji health check dan katalog publik.

TerminalSalin
curl -i http://localhost:8080/healthz
curl -i "http://localhost:8080/v1/products?category=serum&page=1&per_page=20"

Uji route customer dengan Bearer token (token didapat dari POST /v1/auth/login).

TerminalSalin
curl -i http://localhost:8080/v1/cart \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

curl -i -X POST http://localhost:8080/v1/checkout \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"shipping_address_id":1,"shipping_method":"regular","payment_method":"va_bca","idempotency_key":"chk-1f2e"}'

Uji route admin (token dengan role admin) dan webhook publik.

TerminalSalin
curl -i -X POST http://localhost:8080/v1/admin/products \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Niacinamide 10% Serum","category":"serum","price":189000,"stock":40,"status":"active"}'

curl -i -X POST http://localhost:8080/v1/payments/webhook \
  -H "X-Signature: <HMAC_HEX>" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_123","type":"payment.paid","order_id":1001}'

Bug e-commerce sering datang dari kontrak yang kabur, bukan syntax Go

Sebagian besar masalah API e-commerce bukan error kompilasi, melainkan keputusan desain yang terbawa kebiasaan dari Express atau Laravel tanpa disesuaikan.

Chapter ini menutup Roadmap 2 dengan satu permukaan API e-commerce yang utuh, merakit semua yang kamu pelajari dari handler sampai auth.

Setelah ini, Roadmap 3 masuk ke PostgreSQL dan pgx. Peta endpoint yang sudah kita desain akan mendapat storage nyata: tabel products, cart_items, orders, order_items, payments, query pagination, transaksi checkout, dan repository yang menerima context.Context. Roadmap 4 menambah service layer dan clean architecture di antara handler dan repository.