REST API 설계 원칙과 실무 구현

REST API란?

REST(Representational State Transfer)는 네트워크를 통해 리소스를 다루기 위한 아키텍처 스타일이다. REST API는 이러한 원칙을 HTTP 프로토콜에 적용해 클라이언트와 서버가 데이터를 주고받도록 설계한 인터페이스다.

예를 들어 게임 서버에서 유저 정보, 인벤토리, 게임 기록을 관리한다고 가정하자. 클라이언트는 HTTP 요청을 통해 유저 정보를 조회하거나 아이템을 사용하고 게임 기록을 확인할 수 있다.

REST API를 설계할 때 중요한 것은 단순히 URL을 만드는 것이 아니다. 리소스의 의미, HTTP 메서드의 역할, 데이터 검증, 오류 처리, 호환성 등을 일관된 규칙으로 정의하는 것이 핵심이다.

이번 글에서는 REST API의 주요 설계 원칙과 Node.js, Express, TypeScript 환경에서의 구현 방법을 살펴본다.

---

리소스 중심 URL 설계

REST API에서 URL은 일반적으로 리소스를 식별하는 역할을 한다.

리소스란 서버가 관리하는 데이터나 개념을 의미한다. 사용자, 상품, 인벤토리, 주문, 게임 기록 등이 대표적인 예다.

동사보다 명사를 사용한다

다음과 같은 URL을 생각해 보자.

GET /getUser/123
POST /createUser
POST /deleteUser/123

이 방식은 URL에 작업의 의미를 직접 포함한다. 하지만 HTTP 메서드 자체가 작업의 성격을 나타내므로 URL에는 리소스를 중심으로 표현하는 편이 일관적이다.

GET    /users/123
POST   /users
DELETE /users/123

각 URL의 의미는 다음과 같다.

• GET /users/123: 특정 사용자 조회
• POST /users: 사용자 생성
• DELETE /users/123: 특정 사용자 삭제

URL은 리소스를 식별하고, HTTP 메서드는 해당 리소스에 수행할 작업을 표현한다.

컬렉션과 개별 리소스를 구분한다

여러 리소스를 나타내는 컬렉션과 특정 리소스를 나타내는 URL을 구분하면 API의 구조가 명확해진다.

목적	HTTP 요청
전체 사용자 조회	GET /users
특정 사용자 조회	GET /users/123
사용자 생성	POST /users
특정 사용자 수정	PATCH /users/123
특정 사용자 삭제	DELETE /users/123
특정 사용자의 인벤토리 조회	GET /users/123/inventory

하위 리소스는 상위 리소스와의 관계를 표현할 때 유용하다.

다만 모든 관계를 중첩 URL로 표현할 필요는 없다. 중첩이 지나치게 깊어지면 URL이 복잡해지고 리소스의 독립적인 접근도 어려워진다.

예를 들어 다음 URL은 지나치게 복잡하다.

GET /users/123/games/456/rooms/789/items/10

아이템이 독립적인 리소스라면 다음과 같이 표현하는 방법도 고려할 수 있다.

GET /items/10

어떤 URL이 적절한지는 데이터의 실제 관계와 리소스의 독립성에 따라 결정한다.

필터링, 정렬, 페이지네이션은 쿼리 파라미터로 표현한다

컬렉션에서 특정 조건에 해당하는 데이터만 조회할 때는 쿼리 파라미터를 사용할 수 있다.

GET /users?status=active
GET /users?sort=createdAt&order=desc
GET /users?page=2&limit=20
GET /users?status=active&sort=createdAt&order=desc&page=2&limit=20

URL 경로는 리소스를 식별하고, 쿼리 파라미터는 조회 조건을 지정한다.

이렇게 규칙을 통일하면 클라이언트가 API를 예측하기 쉬워지고 서버에서도 공통 조회 로직을 구현하기 편해진다.

---

HTTP 메서드와 상태 코드

REST API에서는 HTTP 메서드와 상태 코드를 적절하게 사용하는 것이 중요하다.

HTTP 메서드는 요청의 목적을 표현하고, 상태 코드는 요청의 처리 결과를 표현한다.

주요 HTTP 메서드

메서드	역할	주요 특징
GET	리소스 조회	서버 상태를 변경하지 않아야 함
POST	리소스 생성 또는 작업 실행	동일 요청의 반복이 중복 작업을 만들 수 있음
PUT	리소스 전체 교체	동일한 요청을 반복해도 의도한 최종 상태가 같아야 함
PATCH	리소스 일부 수정	변경할 필드만 전달 가능
DELETE	리소스 삭제	동일 요청을 반복해도 최종 삭제 상태가 유지되어야 함

여기서 중요한 개념은 멱등성(Idempotency) 이다.

멱등성은 동일한 요청을 여러 번 수행하더라도 서버에 반영되는 최종 상태가 같다는 의미다.

GET, PUT, DELETE는 HTTP 의미상 멱등성을 가져야 한다. 반면 POST는 일반적으로 멱등하지 않지만, 결제나 주문 생성 API에 멱등성 키를 도입하면 중복 처리를 방지하도록 설계할 수 있다.

예를 들어 클라이언트가 결제 요청을 보낸 뒤 응답을 받지 못했다고 가정하자. 클라이언트가 같은 요청을 다시 보내면 결제가 두 번 처리될 수 있다.

이를 방지하기 위해 다음과 같이 요청할 수 있다.

POST /payments
Idempotency-Key: 7e9c1f20-unique-request-id
Content-Type: application/json

서버는 해당 키와 처리 결과를 저장하고 동일한 키로 들어온 요청에 대해 기존 결과를 반환하도록 구현할 수 있다. 실제 결제 처리에서는 키의 유효 범위, 동시 요청 제어, 결과 보존 기간도 함께 정의해야 한다.

주요 HTTP 상태 코드

상태 코드	의미	사용 사례
200 OK	요청 성공	데이터 조회, 수정 결과 반환
201 Created	리소스 생성 성공	사용자 생성
202 Accepted	처리 요청 접수	비동기 작업 접수
204 No Content	요청 성공, 응답 본문 없음	삭제 성공
400 Bad Request	잘못된 요청	JSON 형식 오류, 일반적인 요청 형식 오류
401 Unauthorized	인증 필요 또는 인증 실패	유효하지 않은 인증 토큰
403 Forbidden	접근 권한 없음	다른 사용자의 관리자 기능 접근
404 Not Found	리소스를 찾을 수 없음	존재하지 않는 사용자 조회
409 Conflict	리소스 상태와 충돌	닉네임 중복, 중복 생성
422 Unprocessable Content	요청 형식은 이해했으나 의미상 처리 불가	유효하지 않은 업무 규칙
429 Too Many Requests	요청 횟수 제한 초과	API Rate Limit 초과
500 Internal Server Error	서버 내부 오류	예상하지 못한 서버 예외
503 Service Unavailable	서비스 일시적 이용 불가	서버 과부하, 점검

상태 코드는 API 전체에서 일관되게 사용해야 한다.

예를 들어 닉네임 중복을 어떤 API에서는 400, 다른 API에서는 409로 반환하면 클라이언트는 오류를 구분하기 어려워진다.

닉네임 중복은 기존 리소스와 충돌하는 상황이므로 일반적으로 409 Conflict를 사용할 수 있다.

반면 닉네임 규칙 위반은 API의 오류 정책에 따라 400 또는 422로 표현할 수 있다. 어느 코드를 선택하든 프로젝트 전체에서 동일한 정책을 유지하는 것이 중요하다.

---

DTO와 데이터베이스 모델 분리

DTO(Data Transfer Object)는 계층 간에 데이터를 전달하기 위한 객체다.

데이터베이스 모델은 실제 저장소의 데이터 구조를 표현한다. 두 객체는 목적이 다르므로 같은 구조를 사용해야 할 이유가 없다.

예를 들어 사용자 테이블이 다음과 같다고 가정하자.

interface UserModel {
  id: number;
  email: string;
  passwordHash: string;
  nickname: string;
  role: string;
  createdAt: Date;
  updatedAt: Date;
}

이 모델에는 인증을 위한 비밀번호 해시와 내부 관리 정보가 포함되어 있다.

이를 API 응답에 그대로 사용하면 클라이언트에 불필요한 내부 데이터가 노출될 수 있다.

따라서 요청 DTO와 응답 DTO를 별도로 정의한다.

요청 DTO

export interface CreateUserRequestDto {
  email: string;
  password: string;
  nickname: string;
}

클라이언트가 사용자를 생성할 때 전달해야 하는 데이터만 정의한다.

응답 DTO

export interface UserResponseDto {
  id: number;
  email: string;
  nickname: string;
  createdAt: string;
}

서버가 클라이언트에 반환할 데이터만 정의한다.

모델을 DTO로 변환한다

interface UserModel {
  id: number;
  email: string;
  passwordHash: string;
  nickname: string;
  role: string;
  createdAt: Date;
  updatedAt: Date;
}

interface UserResponseDto {
  id: number;
  email: string;
  nickname: string;
  createdAt: string;
}

function toUserResponseDto(
  user: UserModel
): UserResponseDto {
  return {
    id: user.id,
    email: user.email,
    nickname: user.nickname,
    createdAt: user.createdAt.toISOString(),
  };
}

이 변환 함수는 내부 데이터 모델을 외부 API 계약으로 변환한다.

passwordHash, role, updatedAt은 응답 DTO에 포함하지 않았으므로 일반 사용자 응답으로 노출되지 않는다.

물론 관리자 API에서 역할 정보가 필요하다면 별도의 관리자 응답 DTO를 정의할 수 있다.

DTO를 분리하는 이유

• 보안: 비밀번호 해시와 내부 필드의 외부 노출 방지
• 유지보수: 데이터베이스 구조 변경이 API에 미치는 영향 최소화
• 검증: 요청마다 허용되는 필드를 명확하게 정의
• 버저닝: API 버전별 응답 구조를 독립적으로 관리
• 계층 분리: 데이터 저장 구조와 클라이언트 계약의 결합도 감소

특히 TypeScript의 타입 정의만으로는 실제 HTTP 요청의 데이터를 검증할 수 없다. 클라이언트는 임의의 JSON을 보낼 수 있으므로 런타임 검증을 별도로 수행해야 한다.

---

입력값 검증

클라이언트가 보내는 데이터는 신뢰할 수 없다.

TypeScript에서 요청 객체의 타입을 지정하더라도 외부에서 전달된 JSON이 해당 타입을 준수한다는 보장은 없다. 따라서 서버에서 요청 데이터를 검증해야 한다.

검증은 크게 다음과 같이 나눌 수 있다.

• 형식 검증: 문자열, 숫자, 이메일 형식, 길이
• 허용값 검증: enum에 정의된 값인지 확인
• 업무 규칙 검증: 닉네임 중복, 잔액 부족 여부
• 권한 검증: 요청한 사용자가 해당 리소스를 변경할 권한이 있는지 확인

Zod를 이용한 런타임 검증

Node.js와 TypeScript 환경에서는 Zod 같은 검증 라이브러리를 활용할 수 있다.

import { z } from "zod";

export const createUserSchema = z.object({
  email: z
    .string()
    .trim()
    .email()
    .max(254),

  password: z
    .string()
    .min(12)
    .max(128),

  nickname: z
    .string()
    .trim()
    .min(2)
    .max(20)
    .regex(
      /^[a-zA-Z0-9가-힣_]+$/,
      "닉네임 형식이 올바르지 않습니다."
    ),
}).strict();

export type CreateUserRequestDto =
  z.infer<typeof createUserSchema>;

위 스키마는 이메일 형식, 비밀번호 길이, 닉네임 규칙을 검증한다.

.strict()는 정의되지 않은 필드가 포함된 요청을 거부하도록 한다. 프로젝트에서 알 수 없는 필드를 무시하거나 제거하는 정책을 사용한다면 그에 맞게 설정하면 된다.

비밀번호 정책은 실제 서비스의 보안 정책에 맞게 결정해야 하며, 입력값 검증만으로 비밀번호 보안이 확보되는 것은 아니다. 비밀번호는 안전한 해시 알고리즘으로 처리해야 한다.

Express 미들웨어에서 검증한다

import { Request, Response, NextFunction } from "express";
import { z } from "zod";

function validateBody<T extends z.ZodTypeAny>(
  schema: T
) {
  return (
    req: Request,
    res: Response,
    next: NextFunction
  ) => {
    const result = schema.safeParse(req.body);

    if (!result.success) {
      return next(
        new ApiError(
          422,
          "VALIDATION_FAILED",
          "요청 데이터가 올바르지 않습니다.",
          result.error.issues.map((issue) => ({
            field: issue.path.join("."),
            message: issue.message,
          }))
        )
      );
    }

    res.locals.validatedBody = result.data;
    next();
  };
}

이 미들웨어는 요청 본문을 검증하고, 검증된 데이터만 이후 처리 단계에 전달한다.

ApiError는 아래에서 정의할 공통 오류 클래스다.

라우터에서는 다음과 같이 적용할 수 있다.

router.post(
  "/users",
  validateBody(createUserSchema),
  createUserController
);

컨트롤러는 req.body를 그대로 신뢰하는 대신 res.locals.validatedBody를 사용하도록 구성할 수 있다.

const dto =
  res.locals.validatedBody as CreateUserRequestDto;

실무에서는 검증 결과의 타입이 컨트롤러까지 자연스럽게 전달되도록 타입 안전성을 강화할 수 있다. 위 코드는 핵심 흐름을 보여주기 위한 단순한 예시다.

중요한 점은 입력값 검증이 데이터베이스 제약 조건을 대체하지 않는다는 것이다. 닉네임 중복 검사를 애플리케이션에서 수행하더라도 동시에 두 요청이 들어올 수 있으므로 데이터베이스의 UNIQUE 제약 조건도 필요하다.

---

공통 오류 응답 설계

API마다 오류 응답 구조가 다르면 클라이언트의 오류 처리 코드가 복잡해진다.

예를 들어 어떤 API는 다음과 같이 응답하고,

{
  "message": "닉네임이 중복되었습니다."
}

다른 API는 다음과 같이 응답한다고 가정하자.

{
  "error": "DUPLICATE_NICKNAME",
  "description": "이미 사용 중인 닉네임입니다."
}

클라이언트는 서로 다른 응답 구조를 모두 처리해야 한다.

따라서 오류 응답을 공통 규격으로 통일하는 것이 좋다.

공통 오류 응답 구조

export interface ApiErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Array<{
      field?: string;
      message: string;
    }>;
    requestId?: string;
  };
}

응답 예시는 다음과 같다.

{
  "error": {
    "code": "DUPLICATE_NICKNAME",
    "message": "이미 사용 중인 닉네임입니다.",
    "details": [
      {
        "field": "nickname",
        "message": "사용할 수 없는 닉네임입니다."
      }
    ],
    "requestId": "req-8f2a1c"
  }
}

각 필드의 역할은 다음과 같다.

• code: 클라이언트가 오류 유형을 식별하는 기계 판독용 코드
• message: 사람이 이해할 수 있는 오류 설명
• details: 필드별 검증 오류 등의 추가 정보
• requestId: 서버 로그와 요청을 연결하기 위한 식별자

클라이언트의 분기 처리는 변경될 수 있는 메시지보다 안정적인 오류 코드에 의존하도록 설계한다.

공통 오류 클래스

export class ApiError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly code: string,
    message: string,
    public readonly details?: Array<{
      field?: string;
      message: string;
    }>
  ) {
    super(message);
    this.name = "ApiError";
  }
}

업무 로직에서 발생한 오류를 ApiError로 표현할 수 있다.

if (existingUser) {
  throw new ApiError(
    409,
    "DUPLICATE_NICKNAME",
    "이미 사용 중인 닉네임입니다.",
    [
      {
        field: "nickname",
        message: "이미 사용 중인 닉네임입니다.",
      },
    ]
  );
}

Express 전역 오류 처리 미들웨어

import {
  Request,
  Response,
  NextFunction,
} from "express";

export function errorHandler(
  err: unknown,
  req: Request,
  res: Response,
  next: NextFunction
) {
  if (res.headersSent) {
    return next(err);
  }

  const requestId = res.locals.requestId as
    | string
    | undefined;

  if (err instanceof ApiError) {
    return res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        ...(err.details
          ? { details: err.details }
          : {}),
        ...(requestId ? { requestId } : {}),
      },
    });
  }

  req.log?.error(
    { err, requestId },
    "Unhandled API error"
  );

  return res.status(500).json({
    error: {
      code: "INTERNAL_SERVER_ERROR",
      message: "서버 내부 오류가 발생했습니다.",
      ...(requestId ? { requestId } : {}),
    },
  });
}

req.log는 요청별 로거가 연결되어 있는 환경을 가정한 예시다. Pino 등을 사용한다면 실제 로깅 미들웨어 구성에 맞게 적용해야 한다.

예상하지 못한 오류의 상세 내용, SQL 쿼리, 스택 트레이스, 인증 정보 등을 클라이언트에 노출해서는 안 된다. 해당 정보는 서버 로그에서 추적하고 클라이언트에는 일반화된 메시지를 반환한다.

전역 오류 미들웨어는 모든 라우터 등록 이후에 연결해야 한다. 또한 Express 버전에 따라 비동기 예외 전달 방식이 다를 수 있으므로 사용 중인 버전의 오류 처리 규칙을 준수해야 한다.

---

페이지네이션과 정렬

데이터가 많아지면 전체 데이터를 한 번에 반환하는 방식은 비효율적이다.

예를 들어 게임 서버에 수십만 개의 유저 기록이 저장되어 있다면 모든 데이터를 조회하고 전송하는 것은 데이터베이스 부하, 네트워크 트래픽, 메모리 사용량을 증가시킨다.

이를 해결하기 위해 페이지네이션을 사용한다.

Offset 기반 페이지네이션

가장 간단한 방식은 page와 limit을 사용하는 것이다.

GET /users?page=2&limit=20

서버는 다음과 같이 조회할 수 있다.

SELECT id, nickname, created_at
FROM users
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 20;

페이지 번호가 1부터 시작한다고 가정하면 OFFSET은 다음과 같이 계산한다.

const page = 2;
const limit = 20;

const offset = (page - 1) * limit;

장점은 구현이 단순하고 특정 페이지로 이동하기 쉽다는 것이다.

반면 페이지 번호가 커질수록 데이터베이스가 많은 행을 건너뛰어야 할 수 있다. 또한 조회 도중 데이터가 추가되거나 삭제되면 페이지 사이에 중복 데이터나 누락이 발생할 수 있다.

따라서 정렬 기준을 명확하게 지정해야 한다.

ORDER BY created_at DESC, id DESC

created_at이 같은 데이터가 존재할 수 있으므로 고유한 id를 보조 정렬 기준으로 사용한다.

Cursor 기반 페이지네이션

대량의 데이터나 실시간으로 데이터가 추가되는 목록에서는 커서 기반 페이지네이션이 유용하다.

GET /users?limit=20&cursor=eyJpZCI6MTAwMH0

커서는 마지막으로 조회한 데이터의 위치를 나타낸다. 실제 서비스에서는 필요한 정렬 기준과 식별자를 인코딩하거나 불투명한 토큰으로 제공할 수 있다.

예를 들어 created_at과 id를 기준으로 내림차순 정렬한다면 다음과 같이 조회할 수 있다.

SELECT id, nickname, created_at
FROM users
WHERE
  created_at < :lastCreatedAt
  OR (
    created_at = :lastCreatedAt
    AND id < :lastId
  )
ORDER BY created_at DESC, id DESC
LIMIT :limit;

이 방식은 이전 페이지의 마지막 데이터보다 뒤에 있는 데이터를 조회한다.

Offset과 Cursor의 선택 기준

기준	Offset	Cursor
구현 난이도	낮음	상대적으로 높음
특정 페이지 이동	편리함	상대적으로 불편함
대규모 데이터	큰 OFFSET에서 비효율적일 수 있음	적절한 인덱스가 있으면 효율적
데이터 변경에 따른 이동 안정성	상대적으로 낮음	정렬 기준에 따라 상대적으로 높음
적합한 사례	관리자 목록, 소규모 검색 결과	피드, 로그, 대규모 게임 기록

커서 기반 방식도 자동으로 일관성을 보장하지는 않는다. 정렬 키가 변경될 수 있는지, 데이터가 삭제되는지, 조회 결과를 특정 시점으로 고정해야 하는지에 따라 추가 설계가 필요하다.

정렬 파라미터 검증

클라이언트가 정렬 조건을 지정하도록 할 때는 허용된 컬럼만 사용할 수 있도록 제한해야 한다.

const allowedSortFields = [
  "createdAt",
  "nickname",
] as const;

type UserSortField =
  (typeof allowedSortFields)[number];

function parseSortField(
  value: string | undefined
): UserSortField {
  if (
    value &&
    allowedSortFields.includes(
      value as UserSortField
    )
  ) {
    return value as UserSortField;
  }

  return "createdAt";
}

SQL의 컬럼명은 일반적인 값 바인딩만으로 처리할 수 없는 경우가 많다. 따라서 사용자 입력을 SQL 문자열에 직접 삽입해서는 안 된다.

실제 쿼리를 생성할 때는 검증된 컬럼명을 사전에 정의된 SQL 표현식과 연결하고, 검색값이나 페이지 크기 등은 파라미터 바인딩을 사용해야 한다.

페이지네이션에서는 최대 limit도 지정하는 것이 좋다. 예를 들어 기본값을 20, 최대값을 100으로 설정하면 클라이언트가 과도한 데이터 조회를 요청하는 상황을 제한할 수 있다.

---

API 버저닝과 하위 호환성

API는 한 번 배포한 뒤에도 계속 변경된다.

응답 필드가 추가되거나 데이터 구조가 변경될 수 있고, 기존 기능이 새로운 방식으로 대체될 수도 있다. 하지만 이미 배포된 클라이언트는 즉시 업데이트되지 않을 수 있다.

따라서 API를 변경할 때는 기존 클라이언트가 정상적으로 동작하는지 고려해야 한다.

URL 기반 버저닝

가장 직관적인 방법은 URL에 버전을 포함하는 것이다.

GET /api/v1/users/123
GET /api/v2/users/123

예를 들어 v1 응답이 다음과 같다고 가정하자.

{
  "id": 123,
  "nickname": "Player01"
}

v2에서는 닉네임과 표시 이름을 분리할 수 있다.

{
  "id": 123,
  "nickname": "player01",
  "displayName": "Player01"
}

기존 클라이언트가 nickname을 표시용 이름으로 사용하고 있었다면 필드의 의미를 변경하는 것은 호환성을 깨뜨릴 수 있다.

이때 v1 계약은 유지하고 v2에서 새로운 의미를 제공하면 클라이언트가 이전 버전에서 새 버전으로 점진적으로 전환할 수 있다.

어떤 변경이 하위 호환적인가?

하위 호환성은 기존 클라이언트가 새로운 서버와 계속 정상적으로 통신할 수 있는지를 기준으로 판단한다.

변경	일반적인 영향
응답에 선택적 필드 추가	기존 클라이언트가 알 수 없는 필드를 무시한다면 대체로 호환적
기존 응답 필드 삭제	호환성을 깨뜨릴 수 있음
필드 타입 변경	호환성을 깨뜨릴 수 있음
필수 요청 필드 추가	기존 클라이언트의 요청이 거부될 수 있음
기존 필드의 의미 변경	동작 오류를 일으킬 수 있음
기존 상태 코드나 오류 코드의 의미 변경	클라이언트 분기 로직에 영향을 줄 수 있음

응답 필드 추가도 모든 클라이언트에서 안전한 것은 아니다. 엄격한 스키마 검증을 사용하거나 필드 목록이 정확히 일치해야 하는 클라이언트라면 필드 추가도 문제가 될 수 있다.

따라서 API 계약을 변경할 때는 실제 클라이언트의 처리 방식을 고려해야 한다.

Express 라우터에서 버전을 분리한다

import { Router } from "express";

const apiRouter = Router();

const v1Router = Router();
const v2Router = Router();

v1Router.get("/users/:id", getUserV1);
v2Router.get("/users/:id", getUserV2);

apiRouter.use("/v1", v1Router);
apiRouter.use("/v2", v2Router);

app.use("/api", apiRouter);

이 구조에서는 다음 두 API가 독립적으로 관리된다.

GET /api/v1/users/123
GET /api/v2/users/123

내부 서비스나 도메인 로직은 가능한 한 공유하고, 버전별 컨트롤러 또는 DTO에서 외부 계약을 분리하는 방식이 효율적이다. 버전이 늘어날 때마다 모든 비즈니스 로직을 복제하면 유지보수 비용이 커진다.

버전 폐기 정책

새 버전이 출시되었다고 해서 기존 버전을 즉시 제거해서는 안 된다.

일반적인 전환 절차는 다음과 같다.

• 새 API 버전 출시
• 기존 버전 사용자에게 변경 사항 안내
• 클라이언트의 새 버전 전환 유도
• 기존 버전의 사용량과 오류율 모니터링
• 정해진 폐기 일정에 따라 기존 버전 종료

API 버저닝은 단순히 URL에 숫자를 붙이는 작업이 아니다. API 계약을 변경하고, 여러 클라이언트 버전을 일정 기간 함께 지원하기 위한 운영 전략이다.

---

REST API 설계 시 추가로 고려할 사항

지금까지 살펴본 원칙 외에도 실제 서비스에서는 다음 사항을 함께 고려해야 한다.

인증과 인가

인증(Authentication)은 사용자가 누구인지 확인하는 과정이고, 인가(Authorization)는 해당 사용자가 특정 리소스에 접근할 수 있는지 확인하는 과정이다.

로그인한 사용자라고 해서 다른 사용자의 정보를 수정할 수 있는 것은 아니다.

PATCH /users/123
Authorization: Bearer <access-token>

서버는 토큰의 유효성뿐 아니라 요청한 사용자가 해당 사용자 정보를 수정할 권한이 있는지도 확인해야 한다.

특히 URL에 포함된 사용자 ID만으로 권한을 판단하면 안 된다.

Rate Limiting

특정 클라이언트가 짧은 시간에 지나치게 많은 요청을 보내는 것을 제한해야 한다.

HTTP/1.1 429 Too Many Requests
Retry-After: 10

로그인, 인증 코드 발급, 검색 API 등은 악용 가능성과 서버 부하를 고려해 적절한 제한 정책을 적용할 수 있다.

로깅과 추적

API 요청에는 요청 ID를 부여하고 로그에 함께 기록하면 장애 분석이 쉬워진다.

로그에는 요청 경로, 응답 상태 코드, 처리 시간, 오류 코드 등을 기록할 수 있다. 단, 비밀번호, 액세스 토큰, 민감한 개인정보는 그대로 기록하지 않아야 한다.

API 문서화

Swagger UI와 OpenAPI를 사용하면 API의 경로, 메서드, 요청 DTO, 응답 DTO, 상태 코드, 인증 방식 등을 명시적으로 관리할 수 있다.

API 계약을 코드와 함께 관리하면 프론트엔드와 백엔드 사이의 불일치를 줄이고 테스트 자동화에도 활용할 수 있다.