[CS Study] 3주차 (3) - RESTful API에 대해

💠 RESTful API

RESTful API란?

REST 원칙을 따르는 웹 API이다.
REST는 REpresentational State Transfer의 약자로, 자원을 URI로 표현하고, HTTP 메서드로 행위를 구분하는 아키텍처 스타일이다.

REST의 핵심 개념

1. 자원(Resource)은 URI로 표현한다.

   • /users, /articles/1
   • 또한, 자원을 표현할때는 복수형 사용이 자연스럽고 권장된다.

2. 행위(Verb)는 HTTP 메서드로 표현한다.

   • 자원에 행위가 드러나면 안된다.

3. 표현(Representation)

   • 자원의 상태는 JSON, XML, TEXT 등으로 표현된다.

RESTful API 요청 예시

• GET /users/1
  • user id가 1인 사용자 정보 조회
• POST /users
  • 새로운 사용자 생성
• PUT /users/1
  • user id가 1인 사용자 정보 전체 수정
• PATCH /users/1
  • user id가 1인 사용자정보 일부 수정
• DELETE /users/1
  • user id가 1인 사용자 삭제

❌ 올바르지 않은 요청 예시

• GET /getUserInfo?id=1
  • 행위가 URI에 드러난다.

REST API의 특징

1. Stateless (무상태성)

   • 서버는 요청 간의 상태를 저장하지 않는다.

2. URI는 자원을 식별 /users/1 → 사용자 ID 1이라는 자원

3. 표준 HTTP 메서드 사용 GET, POST 등으로 행위를 명확하게 표현

자원의 표현 시 단수형을 사용할 수도 있다.

URI를 통해 자원을 표현할때, 복수형 사용이 자연스럽고 권장된다.

• /users, /users/1
  

하지만 복수형이 자연스럽기 때문이지, 복수형 표현이 항상 올바른 것은 아니며, 단수형 표현이 오히려 더 자연스러운 경우도 있다.

예를 들어 고유 자원, 전역 설정 등 특정 맥락에서는 단수형으로 표현한는 게 더 적절하다.

• /profile

또는 한국어 단어를 그대로 영어 표기할 때 표현이나 발음이 이상한 경우, 단수형을 쓰는게 더 가독성이 좋다.

• /moim / /moims
  • 발음도 이상하고, 영어 사용자도 무슨 뜻인지 모를 수 있다.
  • 이런 경우 그냥 /moim을 사용하는게 깔끔하고 자연스럽다.

중요한 건 가독성과 팀 내에서 일관된 규칙을 정하고 유지하는 것이다.