REST API 설계

REST API는 웹 서비스 간 통신을 위한 가장 널리 사용되는 아키텍처 스타일입니다. 올바른 REST API 설계는 클라이언트가 예측 가능하게 서버와 상호작용할 수 있게 하며, 유지보수성과 확장성을 높여줍니다. Go는 간결한 문법과 강력한 표준 라이브러리 덕분에 REST API 서버 구현에 매우 적합합니다.

REST 원칙과 URL 설계

REST(Representational State Transfer)의 핵심은 자원(Resource) 중심 설계 입니다.

URL 설계 원칙

# 좋은 URL 설계 (명사 사용, 계층 구조 표현)
GET    /v1/users           # 사용자 목록 조회
POST   /v1/users           # 사용자 생성
GET    /v1/users/{id}      # 특정 사용자 조회
PUT    /v1/users/{id}      # 사용자 전체 수정
PATCH  /v1/users/{id}      # 사용자 부분 수정
DELETE /v1/users/{id}      # 사용자 삭제

GET    /v1/users/{id}/posts        # 사용자의 게시글 목록
GET    /v1/users/{id}/posts/{pid}  # 사용자의 특정 게시글

# 잘못된 URL 설계 (동사 사용 지양)
GET    /getUsers
POST   /createUser
GET    /getUserById?id=1

HTTP 메서드 의미론

메서드	의미	멱등성	안전성
GET	조회	O	O
POST	생성	X	X
PUT	전체 수정	O	X
PATCH	부분 수정	X	X
DELETE	삭제	O	X

멱등성(Idempotent): 동일한 요청을 여러 번 해도 결과가 동일함 안전성(Safe): 서버 상태를 변경하지 않음

HTTP 상태 코드 올바른 사용

// 상태 코드별 사용 시나리오
const (
    // 2xx 성공
    StatusOK        = 200 // GET, PUT, PATCH 성공
    StatusCreated   = 201 // POST로 리소스 생성 성공
    StatusNoContent = 204 // DELETE 성공 (응답 바디 없음)

    // 4xx 클라이언트 오류
    StatusBadRequest          = 400 // 잘못된 요청 형식
    StatusUnauthorized        = 401 // 인증 필요
    StatusForbidden           = 403 // 권한 없음 (인증은 됐지만)
    StatusNotFound            = 404 // 리소스 없음
    StatusMethodNotAllowed    = 405 // 허용되지 않은 HTTP 메서드
    StatusConflict            = 409 // 리소스 충돌 (중복 생성 등)
    StatusUnprocessableEntity = 422 // 유효성 검사 실패

    // 5xx 서버 오류
    StatusInternalServerError = 500 // 서버 내부 오류
    StatusServiceUnavailable  = 503 // 서비스 일시 불가
)

표준 에러 응답 구조체

일관된 에러 응답은 클라이언트가 에러를 예측 가능하게 처리할 수 있게 합니다.

package main

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

// APIError 표준 에러 응답 구조체
type APIError struct {
    Code    string        `json:"code"`
    Message string        `json:"message"`
    Details []ErrorDetail `json:"details,omitempty"`
}

// ErrorDetail 필드별 유효성 오류 상세
type ErrorDetail struct {
    Field   string `json:"field"`
    Message string `json:"message"`
}

// APIResponse 표준 응답 래퍼
type APIResponse[T any] struct {
    Data    T          `json:"data,omitempty"`
    Error   *APIError  `json:"error,omitempty"`
    Meta    *PageMeta  `json:"meta,omitempty"`
}

// PageMeta 페이지네이션 메타데이터
type PageMeta struct {
    Total  int64 `json:"total"`
    Page   int   `json:"page"`
    Limit  int   `json:"limit"`
    HasNext bool `json:"has_next"`
}

// WriteJSON JSON 응답 헬퍼
func WriteJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(v)
}

// WriteError 에러 응답 헬퍼
func WriteError(w http.ResponseWriter, status int, code, message string, details ...ErrorDetail) {
    resp := APIResponse[any]{
        Error: &APIError{
            Code:    code,
            Message: message,
            Details: details,
        },
    }
    WriteJSON(w, status, resp)
}

URL 버전 관리

package main

import (
    "fmt"
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    // v1 라우트
    v1 := http.NewServeMux()
    v1.HandleFunc("GET /users", v1GetUsers)
    v1.HandleFunc("POST /users", v1CreateUser)

    // v2 라우트 (하위 호환성 유지하며 기능 추가)
    v2 := http.NewServeMux()
    v2.HandleFunc("GET /users", v2GetUsers) // 응답 형식 변경
    v2.HandleFunc("POST /users", v2CreateUser)

    // 버전 프리픽스로 분리
    mux.Handle("/v1/", http.StripPrefix("/v1", v1))
    mux.Handle("/v2/", http.StripPrefix("/v2", v2))

    fmt.Println("서버 시작: http://localhost:8080")
    http.ListenAndServe(":8080", mux)
}

func v1GetUsers(w http.ResponseWriter, r *http.Request) {
    WriteJSON(w, http.StatusOK, map[string]any{
        "users": []map[string]string{
            {"id": "1", "name": "홍길동"},
        },
    })
}

func v2GetUsers(w http.ResponseWriter, r *http.Request) {
    // v2는 페이지네이션 메타 포함
    WriteJSON(w, http.StatusOK, APIResponse[any]{
        Data: []map[string]string{
            {"id": "1", "name": "홍길동"},
        },
        Meta: &PageMeta{Total: 1, Page: 1, Limit: 20, HasNext: false},
    })
}

func v1CreateUser(w http.ResponseWriter, r *http.Request) {}
func v2CreateUser(w http.ResponseWriter, r *http.Request) {}

페이지네이션

Offset 기반 페이지네이션

package main

import (
    "net/http"
    "strconv"
)

type PaginationParams struct {
    Page  int // 1부터 시작
    Limit int
    Offset int
}

// ParsePagination 쿼리 파라미터에서 페이지네이션 파싱
func ParsePagination(r *http.Request) PaginationParams {
    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
    limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))

    if page < 1 {
        page = 1
    }
    if limit < 1 || limit > 100 {
        limit = 20 // 기본값, 최대 100
    }

    return PaginationParams{
        Page:   page,
        Limit:  limit,
        Offset: (page - 1) * limit,
    }
}

// 사용 예시
func handleGetPosts(w http.ResponseWriter, r *http.Request) {
    p := ParsePagination(r)

    // DB 쿼리: SELECT * FROM posts LIMIT ? OFFSET ?
    // posts, total := db.GetPosts(p.Limit, p.Offset)
    posts := []map[string]any{} // 실제로는 DB에서 조회
    total := int64(0)

    WriteJSON(w, http.StatusOK, APIResponse[any]{
        Data: posts,
        Meta: &PageMeta{
            Total:   total,
            Page:    p.Page,
            Limit:   p.Limit,
            HasNext: int64(p.Page*p.Limit) < total,
        },
    })
}

Cursor 기반 페이지네이션

대용량 데이터에서 offset 방식은 성능 문제가 있습니다. cursor 방식이 더 효율적입니다.

package main

import (
    "encoding/base64"
    "fmt"
    "net/http"
)

type CursorParams struct {
    Cursor string
    Limit  int
}

// EncodeCursor cursor를 base64로 인코딩 (ID 기반)
func EncodeCursor(id int64) string {
    return base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%d", id)))
}

// DecodeCursor cursor 디코딩
func DecodeCursor(cursor string) (int64, error) {
    b, err := base64.StdEncoding.DecodeString(cursor)
    if err != nil {
        return 0, err
    }
    var id int64
    _, err = fmt.Sscanf(string(b), "%d", &id)
    return id, err
}

// cursor 기반 응답 구조
type CursorResponse[T any] struct {
    Data       T      `json:"data"`
    NextCursor string `json:"next_cursor,omitempty"`
    HasNext    bool   `json:"has_next"`
}

func handleGetPostsCursor(w http.ResponseWriter, r *http.Request) {
    cursor := r.URL.Query().Get("cursor")

    var afterID int64
    if cursor != "" {
        id, err := DecodeCursor(cursor)
        if err != nil {
            WriteError(w, http.StatusBadRequest, "INVALID_CURSOR", "잘못된 커서입니다")
            return
        }
        afterID = id
    }

    // DB 쿼리: SELECT * FROM posts WHERE id > ? ORDER BY id LIMIT ?
    _ = afterID
    posts := []map[string]any{} // 실제 DB 조회
    hasNext := false

    var nextCursor string
    if hasNext {
        // 마지막 항목의 ID로 다음 커서 생성
        // nextCursor = EncodeCursor(posts[len(posts)-1].ID)
    }

    WriteJSON(w, http.StatusOK, CursorResponse[any]{
        Data:       posts,
        NextCursor: nextCursor,
        HasNext:    hasNext,
    })
}

필터링·정렬·검색

package main

import (
    "net/http"
    "strings"
)

type PostFilter struct {
    AuthorID int64
    Status   string
    Search   string
    SortBy   string
    SortDir  string
}

// ParsePostFilter 쿼리 파라미터에서 필터 파싱
func ParsePostFilter(r *http.Request) PostFilter {
    q := r.URL.Query()

    sortDir := strings.ToUpper(q.Get("sort_dir"))
    if sortDir != "ASC" && sortDir != "DESC" {
        sortDir = "DESC"
    }

    sortBy := q.Get("sort_by")
    // 허용된 컬럼만 받기 (SQL 인젝션 방지)
    allowedSortFields := map[string]bool{"created_at": true, "title": true, "views": true}
    if !allowedSortFields[sortBy] {
        sortBy = "created_at"
    }

    return PostFilter{
        Status:  q.Get("status"),
        Search:  q.Get("q"),
        SortBy:  sortBy,
        SortDir: sortDir,
    }
}

// 요청 예시:
// GET /v1/posts?status=published&q=golang&sort_by=views&sort_dir=DESC&page=1&limit=10
func handleFilteredPosts(w http.ResponseWriter, r *http.Request) {
    filter := ParsePostFilter(r)
    p := ParsePagination(r)

    _ = filter
    _ = p

    // DB 쿼리 빌드 후 실행
    WriteJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}

실전 예제: Gin 기반 Blog REST API

package main

import (
    "net/http"
    "strconv"
    "sync"
    "time"

    "github.com/gin-gonic/gin"
)

// Post 블로그 게시글 모델
type Post struct {
    ID        int64     `json:"id"`
    Title     string    `json:"title" binding:"required,min=1,max=200"`
    Content   string    `json:"content" binding:"required"`
    AuthorID  int64     `json:"author_id"`
    Status    string    `json:"status"` // draft, published
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

// CreatePostRequest 게시글 생성 요청
type CreatePostRequest struct {
    Title   string `json:"title" binding:"required,min=1,max=200"`
    Content string `json:"content" binding:"required"`
    Status  string `json:"status" binding:"omitempty,oneof=draft published"`
}

// UpdatePostRequest 게시글 수정 요청
type UpdatePostRequest struct {
    Title   *string `json:"title" binding:"omitempty,min=1,max=200"`
    Content *string `json:"content"`
    Status  *string `json:"status" binding:"omitempty,oneof=draft published"`
}

// PostStore 인메모리 저장소
type PostStore struct {
    mu     sync.RWMutex
    posts  map[int64]*Post
    nextID int64
}

func NewPostStore() *PostStore {
    return &PostStore{posts: make(map[int64]*Post), nextID: 1}
}

func (s *PostStore) Create(req CreatePostRequest) *Post {
    s.mu.Lock()
    defer s.mu.Unlock()

    status := req.Status
    if status == "" {
        status = "draft"
    }

    post := &Post{
        ID:        s.nextID,
        Title:     req.Title,
        Content:   req.Content,
        AuthorID:  1,
        Status:    status,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    }
    s.posts[s.nextID] = post
    s.nextID++
    return post
}

func (s *PostStore) GetAll(page, limit int) ([]*Post, int64) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    all := make([]*Post, 0, len(s.posts))
    for _, p := range s.posts {
        all = append(all, p)
    }

    total := int64(len(all))
    start := (page - 1) * limit
    if start >= len(all) {
        return []*Post{}, total
    }
    end := start + limit
    if end > len(all) {
        end = len(all)
    }
    return all[start:end], total
}

func (s *PostStore) GetByID(id int64) (*Post, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()
    p, ok := s.posts[id]
    return p, ok
}

func (s *PostStore) Update(id int64, req UpdatePostRequest) (*Post, bool) {
    s.mu.Lock()
    defer s.mu.Unlock()

    post, ok := s.posts[id]
    if !ok {
        return nil, false
    }
    if req.Title != nil {
        post.Title = *req.Title
    }
    if req.Content != nil {
        post.Content = *req.Content
    }
    if req.Status != nil {
        post.Status = *req.Status
    }
    post.UpdatedAt = time.Now()
    return post, true
}

func (s *PostStore) Delete(id int64) bool {
    s.mu.Lock()
    defer s.mu.Unlock()

    if _, ok := s.posts[id]; !ok {
        return false
    }
    delete(s.posts, id)
    return true
}

// PostHandler Gin 핸들러 모음
type PostHandler struct {
    store *PostStore
}

func (h *PostHandler) List(c *gin.Context) {
    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
    limit, _ := strconv.Atoi(c.DefaultQuery("limit", "20"))
    if page < 1 { page = 1 }
    if limit < 1 || limit > 100 { limit = 20 }

    posts, total := h.store.GetAll(page, limit)
    c.JSON(http.StatusOK, gin.H{
        "data": posts,
        "meta": gin.H{
            "total":    total,
            "page":     page,
            "limit":    limit,
            "has_next": int64(page*limit) < total,
        },
    })
}

func (h *PostHandler) Create(c *gin.Context) {
    var req CreatePostRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusUnprocessableEntity, gin.H{
            "error": gin.H{"code": "VALIDATION_ERROR", "message": err.Error()},
        })
        return
    }
    post := h.store.Create(req)
    c.JSON(http.StatusCreated, gin.H{"data": post})
}

func (h *PostHandler) Get(c *gin.Context) {
    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "error": gin.H{"code": "INVALID_ID", "message": "유효하지 않은 ID입니다"},
        })
        return
    }

    post, ok := h.store.GetByID(id)
    if !ok {
        c.JSON(http.StatusNotFound, gin.H{
            "error": gin.H{"code": "NOT_FOUND", "message": "게시글을 찾을 수 없습니다"},
        })
        return
    }
    c.JSON(http.StatusOK, gin.H{"data": post})
}

func (h *PostHandler) Update(c *gin.Context) {
    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "error": gin.H{"code": "INVALID_ID", "message": "유효하지 않은 ID입니다"},
        })
        return
    }

    var req UpdatePostRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusUnprocessableEntity, gin.H{
            "error": gin.H{"code": "VALIDATION_ERROR", "message": err.Error()},
        })
        return
    }

    post, ok := h.store.Update(id, req)
    if !ok {
        c.JSON(http.StatusNotFound, gin.H{
            "error": gin.H{"code": "NOT_FOUND", "message": "게시글을 찾을 수 없습니다"},
        })
        return
    }
    c.JSON(http.StatusOK, gin.H{"data": post})
}

func (h *PostHandler) Delete(c *gin.Context) {
    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "error": gin.H{"code": "INVALID_ID", "message": "유효하지 않은 ID입니다"},
        })
        return
    }

    if !h.store.Delete(id) {
        c.JSON(http.StatusNotFound, gin.H{
            "error": gin.H{"code": "NOT_FOUND", "message": "게시글을 찾을 수 없습니다"},
        })
        return
    }
    c.Status(http.StatusNoContent)
}

func main() {
    r := gin.Default()
    handler := &PostHandler{store: NewPostStore()}

    v1 := r.Group("/v1")
    {
        posts := v1.Group("/posts")
        {
            posts.GET("", handler.List)
            posts.POST("", handler.Create)
            posts.GET("/:id", handler.Get)
            posts.PATCH("/:id", handler.Update)
            posts.DELETE("/:id", handler.Delete)
        }
    }

    // 헬스체크
    r.GET("/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"status": "ok"})
    })

    r.Run(":8080")
}

Content-Type 협상

package main

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

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

// 클라이언트의 Accept 헤더에 따라 응답 형식 선택
func handleUser(w http.ResponseWriter, r *http.Request) {
    user := User{ID: 1, Name: "홍길동"}

    accept := r.Header.Get("Accept")
    switch accept {
    case "application/xml":
        w.Header().Set("Content-Type", "application/xml")
        xml.NewEncoder(w).Encode(user)
    default: // application/json or */*
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(user)
    }
}

고수 팁

1. 일관된 응답 구조 유지: 성공/실패 모두 동일한 래퍼 사용

2. 에러 코드는 문자열로: "NOT_FOUND" 형태가 숫자보다 클라이언트에서 처리하기 쉽습니다

3. 멱등 키(Idempotency-Key): POST 요청 중복 방지를 위해 헤더로 유니크 키 처리

// 멱등 키로 중복 요청 방지
func handleCreateOrder(w http.ResponseWriter, r *http.Request) {
    idempotencyKey := r.Header.Get("Idempotency-Key")
    if idempotencyKey == "" {
        WriteError(w, http.StatusBadRequest, "MISSING_IDEMPOTENCY_KEY",
            "Idempotency-Key 헤더가 필요합니다")
        return
    }
    // 캐시에서 이미 처리된 요청인지 확인
    // if cached := cache.Get(idempotencyKey); cached != nil { ... }
}

4. 요청 ID 전파: 모든 요청에 고유 ID 부여 후 응답 헤더에 포함

import "github.com/google/uuid"

func RequestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := uuid.New().String()
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r)
    })
}