REST API란 무엇이고, 좋은 API 디자인 규칙은?

서버 개발을 하다 보면 가장 자주 듣는 단어 중 하나가 바로 API입니다.
그중에서도 특히 REST API는 거의 모든 웹 서비스에서 기본처럼 사용되고 있죠.

이번 글에서는 REST API란 무엇인지, 그리고 좋은 API 디자인 규칙은 무엇인지 정리해보겠습니다.

1. API란 무엇인가?

  • API (Application Programming Interface)
  • 뜻: "어플리케이션끼리 데이터를 주고받을 수 있는 인터페이스"

👉 쉽게 말해, 서버와 클라이언트가 대화하는 창구입니다.

예를 들어:

  • 클라이언트: “아이디 1번 유저 정보 좀 줘!”
  • 서버: “여기 있어요. 이름은 홍길동이고, 나이는 25살입니다.”

이때 요청과 응답의 규칙을 정해놓은 것이 바로 API입니다.

2. REST란 무엇인가?

  • REST (Representational State Transfer)
  • 웹의 기본 원칙(리소스, HTTP 프로토콜)을 따르는 아키텍처 스타일

REST의 핵심 개념은 리소스(Resource)입니다.

  • 리소스 = 우리가 다루려는 대상 (ex. 사용자, 게시글, 댓글)
  • 리소스를 고유하게 식별하는 방법 = URI (Uniform Resource Identifier)

3. REST API의 특징

  1. 리소스 기반
    • 모든 것은 "명사" 리소스로 표현
    • /users, /posts, /comments
  2. 표준 HTTP 메서드 사용
    • GET: 조회
    • POST: 생성
    • PUT/PATCH: 수정
    • DELETE: 삭제
  3. 무상태성(Stateless)
    • 서버는 클라이언트의 상태를 보존하지 않음
    • 요청은 독립적이어야 함
  4. 일관성 있는 URI
    • /users/1/posts/5 → "유저 1번이 작성한 게시글 5번"

4. REST API 예시

(1) 사용자(User) API

  • 조회(GET)
GET /users GET /users/1
 
  • 생성(POST)
POST /users Body: { "name": "홍길동", "age": 25 }

 

  • 수정(PUT)
PUT /users/1 Body: { "name": "김철수", "age": 27 }
 
  • 삭제(DELETE)
DELETE /users/1

 

👉 이렇게 보면 마치 CRUD (Create, Read, Update, Delete) 작업을 HTTP 메서드에 매핑한 것처럼 보입니다.

5. 좋은 API 디자인 규칙

(1) 명확하고 직관적인 URI

  • O: /users/1/posts
  • X: /getUserPost?id=1

👉 REST API는 "동사"가 아니라 "명사"로 표현하는 게 기본입니다.

(2) 일관된 규칙

  • 컬렉션은 복수형 → /users, /posts
  • 계층 관계 → /users/1/posts

(3) 적절한 HTTP 상태 코드 사용

  • 200 OK → 요청 성공
  • 201 Created → 새로운 리소스 생성 성공
  • 400 Bad Request → 잘못된 요청
  • 401 Unauthorized → 인증 실패
  • 403 Forbidden → 권한 없음
  • 404 Not Found → 리소스 없음
  • 500 Internal Server Error → 서버 내부 에러

👉 상태 코드를 제대로 쓰면, 클라이언트는 응답만 보고도 상황을 이해할 수 있습니다.

(4) 응답 포맷은 JSON 권장

{ "id": 1, "name": "홍길동", "age": 25 }

👉 JSON은 가볍고, 대부분의 언어에서 쉽게 파싱할 수 있습니다.

(5) 페이징, 정렬, 필터링 지원

GET /users?page=2&size=20&sort=name,asc

👉 데이터가 많아지면 페이징 처리 없이는 API가 무겁게 동작합니다.

(6) 보안 고려

  • HTTPS는 기본
  • 인증/인가 → JWT, OAuth2.0 같은 방식 활용
  • 민감한 정보는 절대 응답에 포함하지 말기 (예: 비밀번호)

6. 좋은 REST API 예시

# 사용자 목록 조회
GET /api/v1/users

# 특정 사용자 조회
GET /api/v1/users/1

# 게시글 작성
POST /api/v1/posts Body: { "title": "첫 글", "content": "안녕하세요!" }

# 게시글 댓글 작성
POST /api/v1/posts/1/comments
Body: { "content": "좋은 글 감사합니다!" }

👉 버전(v1, v2) 관리도 URI에 포함시키는 게 일반적입니다.

7. 서버 개발자가 REST API 설계할 때 주의할 점

  1. API 문서화
    • Swagger, Postman, Spring REST Docs 같은 도구 사용
    • 팀원/프론트엔드와 소통할 때 필수
  2. 일관성 유지
    • 한 API는 JSON, 다른 API는 XML → ❌ 혼란 초래
  3. 적절한 예외 처리
    • "500에러만 뱉는 API"는 최악
    • 에러 응답도 JSON 형식으로 제공
{
  "error": "USER_NOT_FOUND",
  "message": "해당 ID의 사용자가 존재하지 않습니다."
}

8. 정리

  • REST API는 현대 웹 서비스의 기본
  • 핵심은 리소스를 명확히 표현하고, HTTP 메서드를 일관되게 활용하는 것
  • 좋은 API는 읽기 쉽고, 예측 가능하며, 일관성 있는 구조를 가짐
  • 서버 개발자는 상태 코드, 보안, 문서화까지 고려해야 함

👉 즉, REST API 설계는 단순히 엔드포인트 만드는 게 아니라, 클라이언트와 서버 간의 약속을 명확히 정의하는 일입니다.

저작자표시 (새창열림)

티스토리툴바