사이드 프로젝트 REST API 설계 with FE

Cori1304·2025년 11월 20일

개요

이번주 일요일 25.11.19에 1차 개발자 회의 주제로 API 설계 회의를 진행하려고 한다. 그때를 위해서 REST API에 대한 기록과 의논할 부분이 무엇이 있을지 서술하려고 한다. (아직 기획이 정리되지 않았기에 세부적인 내용을 정할 수 없지만 미래 정할 수 있는것을 정하려고 한다)

REST API란?

REST API는 REST 아키텍처 스타일의 설계 원칙을 따르는 애플리케이션 프로그래밍 인터페이스(API)입니다. REST는 Representational State Transfer의 약자로, 웹 API를 구축하는 방법에 대한 일련의 규칙과 지침입니다. Red Hat 인용

Rest API란 REST한 규칙을 지키는 API를 말하고 이 규칙을 지킨 API를 RESTful하다고 칭 합니다.

REST API 예제

👥 기본 자원 관리: 사용자 (/users)

작업 (CRUD)	HTTP 메서드	URI 경로 예시	설명	일반적인 상태 코드
모두 조회 (Read)	`GET`	`/users`	모든 사용자 목록을 조회합니다.	`200 OK`
단일 조회 (Read)	`GET`	`/users/{id}`	특정 ID의 사용자를 조회합니다. (예: `/users/123`)	`200 OK`, `404 Not Found`
생성 (Create)	`POST`	`/users`	새로운 사용자를 생성합니다. (요청 본문 사용)	`201 Created`
전체 수정 (Update)	`PUT`	`/users/{id}`	특정 자원을 전체 데이터로 교체/업데이트합니다.	`200 OK`, `204 No Content`
일부 수정 (Update)	`PATCH`	`/users/{id}`	특정 자원의 일부 속성만 수정합니다.	`200 OK`, `204 No Content`
삭제 (Delete)	`DELETE`	`/users/{id}`	특정 자원을 삭제합니다.	`204 No Content`

🔗 관계형 자원 관리: 게시물과 댓글

작업	HTTP 메서드	URI 경로 예시	설명
자식 목록 조회	`GET`	`/posts/123/comments`	게시물 123에 속한 모든 댓글을 조회합니다.
자식 생성	`POST`	`/posts/123/comments`	게시물 123에 새 댓글을 생성합니다.
특정 자식 조회	`GET`	`/posts/123/comments/456`	게시물 123의 댓글 456을 조회합니다.

⚙️ 기타 행위 및 쿼리 표현

상황	HTTP 메서드	URI 경로 예시	설명
특정 행위 (액션)	`POST`	`/orders/500/pay`	주문 500에 대해 결제(`pay`)를 실행합니다.
검색/필터링	`GET`	`/products?category=food&sort=price`	쿼리 파라미터를 사용하여 자원을 검색하거나 필터링합니다.

의논할 부분

JWT 사용시 refresh와 access Token을 cookie only로 설정?
이미지 사용시 multipart/form-data 사용? CDN 사용? (Server-Side Upload or Direct Upload)

Exception 처리
- body에 들어갈 데이터를 어떻게 둘것인가?
timestamp,status, msg, code, details

 /*예시*/
{
    "timestamp": "2025-11-22T07:30:00Z",
    "status": 401,
    "code": "AUTH_001",
    "message": "Access token expired. Please refresh your token.",
    "details": null
}