RFC 7807: Problem Details for HTTP APIs

Daftar Isi

1. Apa Itu RFC 7807?

2. Mengapa RFC 7807 Penting?

3. Anatomi Problem Details

4. Field Wajib vs Opsional

5. Media Type yang Digunakan

6. Ekstensi Custom Fields

7. Implementasi Golang — Production Ready

   • Struktur Project

   • Core Problem Details Package

   • Error Registry & Problem Types

   • Middleware untuk HTTP Handler

   • Contoh Handler Lengkap

   • Validasi & Error Extension

   • Logging & Observability

8. Testing Problem Details

9. Perbandingan: Sebelum vs Sesudah RFC 7807

10. Best Practices & Anti-Pattern

11. Penutup

---

Apa Itu RFC 7807?

RFC 7807 adalah standar IETF (Internet Engineering Task Force) yang berjudul "Problem Details for HTTP APIs". Standar ini dipublikasikan pertama kali pada Maret 2016 dan mendefinisikan sebuah format respons error yang konsisten untuk HTTP API. Pada September 2022, versi kedua yaitu RFC 9457 dirilis sebagai pembaruan minor, namun RFC 7807 tetap menjadi rujukan yang paling banyak digunakan dan dikenal di industri.

Secara sederhana, RFC 7807 menjawab satu pertanyaan mendasar yang sering diabaikan oleh banyak developer: "Ketika API-ku error, bagaimana aku harus memberi tahu client secara konsisten?"

Sebelum adanya standar ini, setiap API punya format error-nya sendiri. Ada yang pakai {"error": "..."}, ada yang pakai {"message": "..."}, ada yang pakai {"code": 400, "description": "..."}, dan seterusnya. Tidak ada kesepakatan. Ini menyulitkan client — terutama ketika satu aplikasi mengonsumsi banyak API dari vendor berbeda.

RFC 7807 hadir sebagai lingua franca untuk error response.

---

Mengapa RFC 7807 Penting?

Bayangkan Anda membangun sebuah sistem e-commerce yang mengintegrasikan tiga layanan berbeda: payment gateway, inventory service, dan shipping service. Ketika terjadi error, masing-masing layanan mungkin mengembalikan format yang berbeda. Tim frontend harus menulis parser khusus untuk setiap layanan. Tim backend harus mendokumentasikan format error yang berbeda untuk tiap service. Ini adalah pemborosan waktu yang serius.

Dengan RFC 7807, semua service mematuhi satu kontrak. Manfaatnya antara lain:

Konsistensi — Semua error dari semua service punya struktur yang sama, sehingga client hanya perlu satu cara untuk memproses error.

Self-descriptive — Error mengandung URI yang bisa dibuka untuk mendapat penjelasan lebih lanjut. Ini mengurangi beban dokumentasi.

Extensible — Format ini mendukung field tambahan, sehingga bisa dikustomisasi tanpa melanggar kontrak.

Machine-readable & Human-readable — Formatnya JSON, mudah diproses oleh kode, namun juga mudah dibaca oleh manusia saat debugging.

---

Anatomi Problem Details

RFC 7807 mendefinisikan objek JSON dengan beberapa field yang telah ditentukan maknanya. Berikut contoh lengkap sebuah Problem Details response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Your request parameters didn't validate.",
  "status": 422,
  "detail": "The 'email' field must be a valid email address. The 'age' field must be a positive integer.",
  "instance": "/account/12345/profile",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "rejected_value": "bukan-email"
    },
    {
      "field": "age",
      "message": "Must be a positive integer",
      "rejected_value": -5
    }
  ]
}

Perhatikan bahwa field errors di atas adalah ekstensi custom — bukan bagian dari standar RFC 7807 itu sendiri, namun diperbolehkan dan sangat umum digunakan.

---

Field Wajib vs Opsional

RFC 7807 mendefinisikan lima field standar. Tidak ada satupun yang benar-benar wajib, namun praktik terbaik mengharuskan setidaknya beberapa di antaranya hadir.

type (string, URI) adalah identifier unik untuk jenis masalah ini. Nilainya harus berupa URI absolut yang, idealnya, ketika dibuka, memberikan dokumentasi tentang masalah tersebut. Jika tidak ada URI khusus, gunakan "about:blank" yang berarti menggunakan status HTTP code sebagai satu-satunya informasi. Contoh: "https://api.yourapp.com/problems/insufficient-funds".

title (string) adalah ringkasan singkat yang bisa dibaca manusia tentang jenis masalah. Penting: nilai ini tidak boleh berubah antar request untuk masalah yang sama. Ia mendeskripsikan jenis masalah, bukan instansi spesifiknya. Contoh: "Insufficient Funds".

status (integer) adalah HTTP status code yang relevan. Meskipun sudah ada di HTTP header, menyertakannya di body berguna ketika response body dilogging atau diproses secara terpisah dari header. Contoh: 422.

detail (string) adalah penjelasan spesifik tentang instansi masalah ini yang berguna untuk client. Berbeda dengan title, field ini boleh (dan sebaiknya) bervariasi per request. Gunakan field ini untuk memberikan konteks yang berguna bagi pengguna atau developer. Contoh: "Your balance of $0.50 is less than the required amount of $10.00".

instance (string, URI) adalah URI yang mengidentifikasi instansi spesifik dari masalah ini. Bisa berupa URI absolut atau relatif. Berguna untuk logging dan tracing — client bisa menyertakannya ketika melaporkan bug. Contoh: "/transactions/abc-123".

---

Media Type yang Digunakan

RFC 7807 mendefinisikan dua media type baru:

• application/problem+json — untuk representasi JSON

• application/problem+xml — untuk representasi XML

Dalam praktik di industri, hampir semua orang menggunakan JSON. Yang penting, response harus menggunakan Content-Type: application/problem+json, bukan application/json. Perbedaan ini sinyal penting bagi client bahwa response ini adalah error dalam format RFC 7807, bukan respons sukses yang berbentuk JSON biasa.

---

Ekstensi Custom Fields

Salah satu kekuatan RFC 7807 adalah kemampuannya untuk di-extend. Anda bebas menambahkan field apapun ke dalam objek Problem Details, asalkan tidak bertabrakan dengan lima field standar di atas. Beberapa ekstensi yang umum digunakan:

{
  "type": "https://api.example.com/problems/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute.",
  "instance": "/api/v1/users",
  
  "retry_after": 45,
  "limit": 100,
  "remaining": 0,
  "reset_at": "2024-01-15T10:30:00Z",
  "trace_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

---

Implementasi Golang — Production Ready

Sekarang kita masuk ke bagian yang paling menarik. Kita akan membangun implementasi RFC 7807 yang lengkap, production-ready, dan mengikuti idiomatic Go.

Struktur Project

myapp/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── problems/
│   │   ├── problem.go        # Core Problem Details struct & helpers
│   │   ├── registry.go       # Centralized problem type registry
│   │   └── middleware.go     # HTTP middleware untuk recovery & logging
│   ├── handler/
│   │   ├── user.go
│   │   └── payment.go
│   └── validator/
│       └── validator.go
├── go.mod
└── go.sum

---

Core Problem Details Package

File internal/problems/problem.go adalah jantung dari implementasi kita. Di sinilah kita mendefinisikan struct dan semua helper yang diperlukan.

// Package problems menyediakan implementasi RFC 7807 Problem Details
// untuk HTTP API responses yang konsisten dan standar.
package problems

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

// ProblemDetails merepresentasikan RFC 7807 Problem Details object.
// Semua field standar sudah didefinisikan. Field tambahan dapat ditambahkan
// melalui mekanisme Extensions.
type ProblemDetails struct {
	// Type adalah URI absolut yang mengidentifikasi jenis masalah.
	// Ketika dibuka, sebaiknya memberikan dokumentasi yang dapat dibaca manusia.
	// Gunakan "about:blank" jika tidak ada URI khusus.
	Type string `json:"type"`

	// Title adalah ringkasan singkat yang bisa dibaca manusia.
	// Nilai ini TIDAK BOLEH berubah antar request untuk masalah yang sama.
	Title string `json:"title"`

	// Status adalah HTTP status code yang relevan.
	Status int `json:"status"`

	// Detail adalah penjelasan spesifik tentang instansi masalah ini.
	// Nilai ini BOLEH berbeda-beda per request.
	Detail string `json:"detail,omitempty"`

	// Instance adalah URI yang mengidentifikasi instansi spesifik masalah.
	Instance string `json:"instance,omitempty"`

	// Extensions berisi field-field tambahan diluar standar RFC 7807.
	// Field-field ini akan di-flatten ke level atas JSON object.
	Extensions map[string]any `json:"-"`
}

// MarshalJSON mengimplementasikan custom JSON marshaling sehingga
// Extensions di-flatten ke level atas, sesuai spesifikasi RFC 7807.
func (p ProblemDetails) MarshalJSON() ([]byte, error) {
	// Mulai dengan field standar
	base := map[string]any{
		"type":   p.Type,
		"title":  p.Title,
		"status": p.Status,
	}

	if p.Detail != "" {
		base["detail"] = p.Detail
	}
	if p.Instance != "" {
		base["instance"] = p.Instance
	}

	// Merge extensions ke level atas, namun field standar tidak boleh ditimpa
	protectedFields := map[string]bool{
		"type": true, "title": true, "status": true,
		"detail": true, "instance": true,
	}

	for k, v := range p.Extensions {
		if !protectedFields[k] {
			base[k] = v
		}
	}

	return json.Marshal(base)
}

// Option adalah functional option untuk mengkustomisasi ProblemDetails.
type Option func(*ProblemDetails)

// WithDetail menambahkan detail message ke ProblemDetails.
func WithDetail(detail string) Option {
	return func(p *ProblemDetails) {
		p.Detail = detail
	}
}

// WithDetailf menambahkan detail message dengan format string.
func WithDetailf(format string, args ...any) Option {
	return func(p *ProblemDetails) {
		p.Detail = fmt.Sprintf(format, args...)
	}
}

// WithInstance menambahkan instance URI ke ProblemDetails.
func WithInstance(instance string) Option {
	return func(p *ProblemDetails) {
		p.Instance = instance
	}
}

// WithExtension menambahkan satu extension field.
func WithExtension(key string, value any) Option {
	return func(p *ProblemDetails) {
		if p.Extensions == nil {
			p.Extensions = make(map[string]any)
		}
		p.Extensions[key] = value
	}
}

// WithExtensions menambahkan multiple extension fields sekaligus.
func WithExtensions(ext map[string]any) Option {
	return func(p *ProblemDetails) {
		if p.Extensions == nil {
			p.Extensions = make(map[string]any)
		}
		for k, v := range ext {
			p.Extensions[k] = v
		}
	}
}

// Write menulis ProblemDetails sebagai HTTP response dengan
// Content-Type yang benar sesuai RFC 7807.
func (p *ProblemDetails) Write(w http.ResponseWriter) {
	w.Header().Set("Content-Type", "application/problem+json; charset=utf-8")
	w.Header().Set("X-Content-Type-Options", "nosniff")
	w.WriteHeader(p.Status)

	if err := json.NewEncoder(w).Encode(p); err != nil {
		// Fallback: jika encoding gagal, tulis error sederhana
		slog.Error("failed to encode problem details", "error", err)
	}
}

// Error mengimplementasikan interface error sehingga ProblemDetails
// bisa digunakan sebagai error dalam Go idiomatik.
func (p *ProblemDetails) Error() string {
	return fmt.Sprintf("[%d] %s: %s", p.Status, p.Type, p.Detail)
}

// IsProblem memeriksa apakah sebuah error adalah *ProblemDetails.
func IsProblem(err error) (*ProblemDetails, bool) {
	p, ok := err.(*ProblemDetails)
	return p, ok
}

---

Error Registry & Problem Types

Membuat problem types tersebar di mana-mana adalah anti-pattern. Sebaiknya, semua problem types diregistrasi di satu tempat. File internal/problems/registry.go:

package problems

import "net/http"

// baseURI adalah prefix untuk semua problem type URI dalam aplikasi ini.
// Ubah sesuai domain Anda.
const baseURI = "https://api.example.com/problems"

// New membuat ProblemDetails baru dari problemType yang sudah didefinisikan,
// dengan menerapkan options yang diberikan.
func New(pt ProblemType, opts ...Option) *ProblemDetails {
	p := &ProblemDetails{
		Type:   pt.Type,
		Title:  pt.Title,
		Status: pt.Status,
	}
	for _, opt := range opts {
		opt(p)
	}
	return p
}

// ProblemType mendefinisikan template untuk sebuah jenis masalah.
// Ini adalah building block yang digunakan untuk membuat instance ProblemDetails.
type ProblemType struct {
	Type   string
	Title  string
	Status int
}

// --- Definisi Problem Types Standar ---
// Semua problem types yang ada dalam aplikasi harus didefinisikan di sini.
// Ini memastikan konsistensi dan memudahkan auditing.

var (
	// ProblemNotFound digunakan ketika resource yang diminta tidak ditemukan.
	ProblemNotFound = ProblemType{
		Type:   baseURI + "/not-found",
		Title:  "Resource Not Found",
		Status: http.StatusNotFound,
	}

	// ProblemValidation digunakan ketika request payload tidak valid.
	ProblemValidation = ProblemType{
		Type:   baseURI + "/validation-error",
		Title:  "Validation Error",
		Status: http.StatusUnprocessableEntity,
	}

	// ProblemUnauthorized digunakan ketika client tidak terautentikasi.
	ProblemUnauthorized = ProblemType{
		Type:   baseURI + "/unauthorized",
		Title:  "Unauthorized",
		Status: http.StatusUnauthorized,
	}

	// ProblemForbidden digunakan ketika client tidak memiliki izin.
	ProblemForbidden = ProblemType{
		Type:   baseURI + "/forbidden",
		Title:  "Forbidden",
		Status: http.StatusForbidden,
	}

	// ProblemConflict digunakan ketika terjadi konflik state (misal: duplikat).
	ProblemConflict = ProblemType{
		Type:   baseURI + "/conflict",
		Title:  "Conflict",
		Status: http.StatusConflict,
	}

	// ProblemRateLimit digunakan ketika client melebihi rate limit.
	ProblemRateLimit = ProblemType{
		Type:   baseURI + "/rate-limit-exceeded",
		Title:  "Too Many Requests",
		Status: http.StatusTooManyRequests,
	}

	// ProblemInsufficientFunds adalah contoh domain-specific problem type.
	ProblemInsufficientFunds = ProblemType{
		Type:   baseURI + "/insufficient-funds",
		Title:  "Insufficient Funds",
		Status: http.StatusUnprocessableEntity,
	}

	// ProblemInternal digunakan untuk internal server error.
	// PERHATIAN: detail-nya tidak boleh mengekspos informasi internal sistem.
	ProblemInternal = ProblemType{
		Type:   baseURI + "/internal-server-error",
		Title:  "Internal Server Error",
		Status: http.StatusInternalServerError,
	}

	// ProblemBadRequest digunakan untuk request yang malformed (misal: JSON invalid).
	ProblemBadRequest = ProblemType{
		Type:   baseURI + "/bad-request",
		Title:  "Bad Request",
		Status: http.StatusBadRequest,
	}
)

---

Middleware untuk HTTP Handler

Middleware ini sangat penting untuk production. Ia menangkap panic, memastikan semua error terdokumentasi, dan menambahkan trace ID ke setiap response.

// internal/problems/middleware.go
package problems

import (
	"errors"
	"log/slog"
	"net/http"
	"runtime/debug"

	"github.com/google/uuid"
)

// RecoveryMiddleware menangkap panic dan mengubahnya menjadi
// RFC 7807 Internal Server Error response. Ini memastikan API
// tidak pernah crash tanpa memberikan respons yang terformat.
func RecoveryMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if rec := recover(); rec != nil {
				// Log full stack trace untuk debugging internal
				slog.Error("panic recovered",
					"panic", rec,
					"stack", string(debug.Stack()),
					"method", r.Method,
					"path", r.URL.Path,
				)

				// Kirim error yang aman ke client — JANGAN ekspos stack trace
				p := New(ProblemInternal,
					WithDetail("An unexpected error occurred. Please try again later."),
					WithInstance(r.URL.Path),
				)
				p.Write(w)
			}
		}()
		next.ServeHTTP(w, r)
	})
}

// TraceMiddleware menambahkan trace ID ke setiap request dan response.
// Trace ID ini memudahkan correlation antara log server dan report dari client.
func TraceMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Gunakan trace ID dari header jika ada (dari upstream proxy/gateway)
		traceID := r.Header.Get("X-Trace-Id")
		if traceID == "" {
			traceID = uuid.NewString()
		}

		// Sertakan trace ID di response header agar client bisa melaporkannya
		w.Header().Set("X-Trace-Id", traceID)

		// Tambahkan ke context untuk digunakan oleh handler
		ctx := withTraceID(r.Context(), traceID)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// WriteError adalah helper untuk menulis error ke response.
// Ia akan otomatis mendeteksi apakah error adalah *ProblemDetails atau tidak.
// Jika bukan, ia akan membungkusnya sebagai Internal Server Error.
func WriteError(w http.ResponseWriter, r *http.Request, err error) {
	traceID := TraceIDFromContext(r.Context())

	var p *ProblemDetails
	if errors.As(err, &p) {
		// Tambahkan trace ID ke semua error response untuk observability
		if p.Extensions == nil {
			p.Extensions = make(map[string]any)
		}
		p.Extensions["trace_id"] = traceID
		p.Instance = r.URL.Path

		// Log pada level yang sesuai berdasarkan status code
		if p.Status >= 500 {
			slog.Error("server error",
				"type", p.Type,
				"status", p.Status,
				"detail", p.Detail,
				"trace_id", traceID,
				"path", r.URL.Path,
			)
		} else {
			slog.Info("client error",
				"type", p.Type,
				"status", p.Status,
				"trace_id", traceID,
				"path", r.URL.Path,
			)
		}
		p.Write(w)
		return
	}

	// Error tidak dikenal — wrap sebagai Internal Server Error
	// Log error aslinya untuk debugging, tapi jangan ekspos ke client
	slog.Error("unhandled error",
		"error", err,
		"trace_id", traceID,
		"path", r.URL.Path,
	)

	p = New(ProblemInternal,
		WithDetail("An unexpected error occurred."),
		WithExtension("trace_id", traceID),
	)
	p.Instance = r.URL.Path
	p.Write(w)
}

---

Validasi & Error Extension

Salah satu use case terpenting RFC 7807 adalah validation error. Kita perlu menampilkan field mana yang bermasalah dan mengapa. Berikut implementasinya menggunakan library go-playground/validator.

// internal/validator/validator.go
package validator

import (
	"github.com/go-playground/validator/v10"
	"myapp/internal/problems"
)

// FieldError merepresentasikan satu error pada satu field.
type FieldError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
	// RejectedValue menyimpan nilai yang ditolak.
	// Hati-hati: jangan ekspos data sensitif seperti password di sini.
	RejectedValue any `json:"rejected_value,omitempty"`
}

var validate = validator.New()

// Validate memvalidasi struct menggunakan tag `validate`.
// Jika validasi gagal, ia mengembalikan *problems.ProblemDetails yang
// berisi detail tentang field-field yang bermasalah.
func Validate(v any) error {
	err := validate.Struct(v)
	if err == nil {
		return nil
	}

	var validationErrors validator.ValidationErrors
	if !errors.As(err, &validationErrors) {
		// Bukan validation error yang kita kenal — kembalikan sebagai-is
		return err
	}

	fieldErrors := make([]FieldError, 0, len(validationErrors))
	for _, fe := range validationErrors {
		fieldErrors = append(fieldErrors, FieldError{
			Field:         toSnakeCase(fe.Field()),
			Message:       humanizeValidationError(fe),
			RejectedValue: sanitizeValue(fe.Field(), fe.Value()),
		})
	}

	return problems.New(
		problems.ProblemValidation,
		problems.WithDetail("One or more fields failed validation. Please check the errors and try again."),
		problems.WithExtension("errors", fieldErrors),
	)
}

// humanizeValidationError mengubah tag validasi menjadi pesan yang mudah dipahami.
func humanizeValidationError(fe validator.FieldError) string {
	switch fe.Tag() {
	case "required":
		return "This field is required"
	case "email":
		return "Must be a valid email address"
	case "min":
		return fmt.Sprintf("Must be at least %s characters long", fe.Param())
	case "max":
		return fmt.Sprintf("Must not exceed %s characters", fe.Param())
	case "gte":
		return fmt.Sprintf("Must be greater than or equal to %s", fe.Param())
	case "lte":
		return fmt.Sprintf("Must be less than or equal to %s", fe.Param())
	case "url":
		return "Must be a valid URL"
	case "uuid4":
		return "Must be a valid UUID v4"
	default:
		return fmt.Sprintf("Failed validation for rule '%s'", fe.Tag())
	}
}

// sensitiveFields berisi nama field yang tidak boleh dikembalikan ke client.
var sensitiveFields = map[string]bool{
	"Password": true, "PasswordConfirm": true,
	"CreditCard": true, "CVV": true, "SSN": true,
}

// sanitizeValue mengembalikan nil untuk field sensitif agar tidak bocor ke client.
func sanitizeValue(fieldName string, value any) any {
	if sensitiveFields[fieldName] {
		return nil
	}
	return value
}

---

Contoh Handler Lengkap

Sekarang mari kita lihat bagaimana semua komponen di atas digunakan bersama dalam handler yang nyata.

// internal/handler/user.go
package handler

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

	"myapp/internal/problems"
	appvalidator "myapp/internal/validator"
)

// CreateUserRequest adalah request body untuk membuat user baru.
type CreateUserRequest struct {
	Name     string `json:"name"     validate:"required,min=2,max=100"`
	Email    string `json:"email"    validate:"required,email"`
	Age      int    `json:"age"      validate:"required,gte=18,lte=120"`
	Password string `json:"password" validate:"required,min=8"`
}

// UserHandler mengelola endpoint yang berkaitan dengan user.
type UserHandler struct {
	// userService adalah dependency untuk logika bisnis user
	userService UserService
}

// NewUserHandler membuat UserHandler baru.
func NewUserHandler(userService UserService) *UserHandler {
	return &UserHandler{userService: userService}
}

// CreateUser menangani request POST /users untuk membuat user baru.
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
	// 1. Decode request body
	var req CreateUserRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		problems.WriteError(w, r, problems.New(
			problems.ProblemBadRequest,
			problems.WithDetail("Request body is not valid JSON. Please check your request format."),
		))
		return
	}

	// 2. Validasi input — jika gagal, akan mengembalikan validation error RFC 7807
	if err := appvalidator.Validate(req); err != nil {
		problems.WriteError(w, r, err)
		return
	}

	// 3. Panggil service layer
	user, err := h.userService.CreateUser(r.Context(), req)
	if err != nil {
		// 4. Handle domain-specific errors dari service layer
		var domainErr *DomainError
		if errors.As(err, &domainErr) {
			switch domainErr.Code {
			case ErrEmailAlreadyExists:
				problems.WriteError(w, r, problems.New(
					problems.ProblemConflict,
					problems.WithDetailf(
						"An account with email '%s' already exists. Please use a different email or log in.",
						req.Email,
					),
				))
			default:
				// Error domain yang tidak dikenal — treat as internal error
				problems.WriteError(w, r, err)
			}
			return
		}
		// Error non-domain — WriteError akan otomatis wrap sebagai 500
		problems.WriteError(w, r, err)
		return
	}

	// 5. Sukses — kembalikan 201 Created
	w.Header().Set("Content-Type", "application/json")
	w.Header().Set("Location", "/users/"+user.ID)
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(user)
}

// GetUser menangani request GET /users/{id}.
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
	userID := r.PathValue("id") // Go 1.22+

	user, err := h.userService.GetUserByID(r.Context(), userID)
	if err != nil {
		if errors.Is(err, ErrUserNotFound) {
			problems.WriteError(w, r, problems.New(
				problems.ProblemNotFound,
				problems.WithDetailf("User with ID '%s' was not found.", userID),
			))
			return
		}
		problems.WriteError(w, r, err)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(user)
}

---

Logging & Observability

Pada implementasi WriteError di middleware, kita sudah menyertakan structured logging menggunakan log/slog (standar library Go 1.21+). Setiap error di-log dengan informasi yang cukup untuk debugging:

// Contoh log output (format JSON untuk production):
{
  "time": "2024-01-15T10:30:00Z",
  "level": "INFO",
  "msg": "client error",
  "type": "https://api.example.com/problems/validation-error",
  "status": 422,
  "trace_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "path": "/api/v1/users"
}

---

Testing Problem Details

Testing adalah bagian yang tidak terpisahkan dari implementasi production-ready. Berikut contoh testing yang komprehensif.

// internal/problems/problem_test.go
package problems_test

import (
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"testing"

	"myapp/internal/problems"
)

func TestProblemDetails_MarshalJSON(t *testing.T) {
	t.Run("hanya field standar", func(t *testing.T) {
		p := problems.New(problems.ProblemNotFound,
			problems.WithDetail("User tidak ditemukan"),
		)

		data, err := json.Marshal(p)
		if err != nil {
			t.Fatalf("unexpected error: %v", err)
		}

		var result map[string]any
		if err := json.Unmarshal(data, &result); err != nil {
			t.Fatalf("failed to unmarshal: %v", err)
		}

		assertField(t, result, "type", problems.ProblemNotFound.Type)
		assertField(t, result, "title", problems.ProblemNotFound.Title)
		assertField(t, result, "status", float64(http.StatusNotFound))
		assertField(t, result, "detail", "User tidak ditemukan")
	})

	t.Run("extensions di-flatten ke level atas", func(t *testing.T) {
		p := problems.New(problems.ProblemValidation,
			problems.WithExtension("errors", []map[string]string{
				{"field": "email", "message": "Invalid email"},
			}),
		)

		data, _ := json.Marshal(p)
		var result map[string]any
		json.Unmarshal(data, &result)

		// "errors" harus ada di level atas, bukan di dalam field "extensions"
		if _, ok := result["errors"]; !ok {
			t.Error("expected 'errors' field at top level")
		}
		if _, ok := result["extensions"]; ok {
			t.Error("'extensions' field should not appear in JSON output")
		}
	})

	t.Run("protected fields tidak bisa ditimpa extension", func(t *testing.T) {
		p := problems.New(problems.ProblemNotFound,
			// Mencoba menimpa field standar via extension — harus diabaikan
			problems.WithExtension("status", 999),
			problems.WithExtension("type", "malicious-type"),
		)

		data, _ := json.Marshal(p)
		var result map[string]any
		json.Unmarshal(data, &result)

		// Status harus tetap 404, bukan 999
		assertField(t, result, "status", float64(http.StatusNotFound))
		assertField(t, result, "type", problems.ProblemNotFound.Type)
	})
}

func TestProblemDetails_Write(t *testing.T) {
	p := problems.New(problems.ProblemNotFound,
		problems.WithDetail("Resource not found"),
	)

	rec := httptest.NewRecorder()
	p.Write(rec)

	// Periksa status code
	if rec.Code != http.StatusNotFound {
		t.Errorf("expected status %d, got %d", http.StatusNotFound, rec.Code)
	}

	// Periksa Content-Type sesuai RFC 7807
	contentType := rec.Header().Get("Content-Type")
	if contentType != "application/problem+json; charset=utf-8" {
		t.Errorf("expected Content-Type 'application/problem+json; charset=utf-8', got '%s'", contentType)
	}

	// Periksa body dapat di-unmarshal
	var result map[string]any
	if err := json.NewDecoder(rec.Body).Decode(&result); err != nil {
		t.Fatalf("response body is not valid JSON: %v", err)
	}
}

// assertField adalah helper untuk memeriksa nilai field dalam map.
func assertField(t *testing.T, m map[string]any, key string, expected any) {
	t.Helper()
	actual, ok := m[key]
	if !ok {
		t.Errorf("expected field '%s' to exist", key)
		return
	}
	if actual != expected {
		t.Errorf("field '%s': expected %v (%T), got %v (%T)", key, expected, expected, actual, actual)
	}
}

---

Contoh Response Lengkap

Berikut adalah contoh response yang akan dihasilkan oleh implementasi kita untuk berbagai skenario:

Validation Error (422):

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields failed validation. Please check the errors and try again.",
  "instance": "/api/v1/users",
  "trace_id": "7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "rejected_value": "bukan-email"
    },
    {
      "field": "age",
      "message": "Must be greater than or equal to 18",
      "rejected_value": 15
    }
  ]
}

Conflict Error (409):

{
  "type": "https://api.example.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "An account with email '[e-mail]' already exists. Please use a different email or log in.",
  "instance": "/api/v1/users",
  "trace_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4"
}

Insufficient Funds (422):

{
  "type": "https://api.example.com/problems/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Your balance of $0.50 is less than the required amount of $25.00.",
  "instance": "/api/v1/payments",
  "trace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "current_balance": 0.50,
  "required_amount": 25.00
}

---

Perbandingan: Sebelum vs Sesudah RFC 7807

Untuk membuat perbedaannya semakin nyata, berikut perbandingan kode sebelum dan sesudah mengadopsi RFC 7807.

Sebelum (tidak konsisten, hard to maintain):

// ❌ Berbagai format error yang tidak konsisten
// Handler A
w.WriteHeader(404)
json.NewEncoder(w).Encode(map[string]string{"error": "not found"})

// Handler B
w.WriteHeader(422)
json.NewEncoder(w).Encode(map[string]any{
    "success": false,
    "message": "Validation failed",
    "fields": validationErrors,
})

// Handler C
w.WriteHeader(500)
json.NewEncoder(w).Encode(map[string]string{
    "code": "INTERNAL_ERROR",
    "description": err.Error(), // ❌ BAHAYA: ekspos internal error ke client!
})

Sesudah (konsisten, aman, standar):

// ✅ Konsisten, aman, mudah di-maintain
// Handler A
problems.WriteError(w, r, problems.New(
    problems.ProblemNotFound,
    problems.WithDetailf("User with ID '%s' was not found.", userID),
))

// Handler B
problems.WriteError(w, r, appvalidator.Validate(req)) // auto RFC 7807

// Handler C — WriteError otomatis handle semua error dengan aman
problems.WriteError(w, r, err)

---

Best Practices & Anti-Pattern

Setelah membahas implementasi, penting untuk mengetahui apa yang harus dilakukan dan apa yang harus dihindari.

Yang harus dilakukan: Selalu gunakan application/problem+json sebagai Content-Type, bukan application/json, untuk response error. Ini sinyal penting bagi client.

Yang harus dilakukan: Daftarkan semua problem types di satu file registry. Ini memudahkan dokumentasi, auditing, dan memastikan konsistensi type URI dan title.

Yang harus dilakukan: Sertakan trace_id di setiap error response. Ini adalah investasi kecil yang menghemat banyak waktu saat debugging di production.

Yang harus dilakukan: Bedakan antara title (deskripsi jenis masalah, tidak berubah) dan detail (deskripsi instansi spesifik, boleh bervariasi).

Yang TIDAK boleh dilakukan: Jangan pernah mengekspos stack trace, nama database, nama internal library, atau pesan error sistem ke dalam field detail untuk error 5xx. Log detail tersebut di server, kirim pesan umum ke client.

Yang TIDAK boleh dilakukan: Jangan membuat problem types yang terlalu granular sampai satu handler bisa menghasilkan puluhan types berbeda. Sebaliknya, jangan juga terlalu generik sehingga semua error masuk ke satu tipe "general-error". Temukan keseimbangan yang baik.

Yang TIDAK boleh dilakukan: Jangan mengembalikan status 200 OK untuk error, lalu menyembunyikan status error di dalam body. Ini melanggar semantik HTTP dan membingungkan proxy, monitoring tool, dan client.

Yang TIDAK boleh dilakukan: Jangan biarkan field type menunjuk ke URI yang tidak ada atau yang mengembalikan 404. Jika URI belum siap, gunakan "about:blank" sementara.

---

Penutup

RFC 7807 adalah salah satu standar API yang paling elegan: sederhana, extensible, dan pragmatis. Ia tidak memaksakan Anda melakukan perombakan besar-besaran, namun secara bertahap membawa konsistensi yang sangat berharga ke seluruh ekosistem API Anda.

Implementasi yang kita bangun di artikel ini mengikuti beberapa prinsip utama: fail safely (panic di-recover, internal errors tidak bocor), observable (trace ID dan structured logging di setiap error), consistent (semua error melewati satu jalur WriteError), dan extensible (mudah menambahkan domain-specific problem types baru).

Jika Anda membangun API baru hari ini, ada satu alasan yang sangat kuat untuk mengadopsi RFC 7807 sejak awal: jauh lebih mudah membangun dengan standar dari awal daripada melakukan migrasi di tengah jalan ketika sudah ada puluhan client yang bergantung pada format error lama Anda.

Selamat membangun API yang lebih baik! 🚀

---

Referensi:

• RFC 7807 - Problem Details for HTTP APIs

• RFC 9457 - Problem Details for HTTP APIs (update)

• go-playground/validator

• Go 1.21 log/slog package