Restful API 설계

이성민·2025년 1월 1일

API란?

API(Application Programming Interface, 애플리케이션 프로그래밍 인터페이스)는 서로 다른 소프트웨어 시스템이 상호작용하고 통신할 수 있도록 정의된 규칙과 프로토콜의 모음입니다. 간단히 말해, API는 한 시스템이나 애플리케이션이 다른 시스템이나 애플리케이션과 정보를 주고받을 수 있는 방법을 제공합니다.

아래 사진을 예를 들어 추가 설명하겠습니다.

치킨을 시켜 먹으려면 배달어플(API)를 이용하여 배달어플(API)이 요구하는 주소, 전화번호, 요구사항, 결재 방법 등을 입력합니다. 그리고 배달어플(API)가 음식점(응용 프로그램)에 주문 정보를 전달합니다. 그리고 치킨이 만들어져 저에게 음식을 가져다 줍니다.
결과적으로, 배달어플(API)은 저와 음식점(응용프로그램) 사이에 중개자 역활을 하며, 정해진 형식에 따라 정보를 주고 받을 수 있도록 도와줍니다.
따라서, API는 위 예시 과정을 봤듯이 서로 다른 시스템이나 응용프로그램간에 소통이 가능하게 해줍니다.

REST란?

REST(REpresentational State Transfer)는 ‘자원(Resource)을 의미(Representation)로 구분하여 그 상태를 전달’ 하는 것을 뜻합니다.
즉, HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미합니다.
추가로, REST라는 단어는 Roy Fielding이 2000년 캘리포니아 대학교 어바인 캠퍼스의 박사논문으로 제출한(https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) 에서 처음으로 언급되었습니다.

REST의 3요소

구성 요소

자원 (Resource): 자원을 식별하기 위한 URI
행위 (Verb): 자원에 대해 수행할 행동을 지정하는 HTTP Method
표현 (Representations): 요청 또는 응답의 내용으로, 자원의 상태를 나타냄

REST 구성 요소 표

구성 요소	내용	표현 방법	예
자원 (Resource)	자원을 식별	HTTP URI	`/members/{1}`, `/member/`
행위 (Verb)	자원에 대한 행위	HTTP Method	`POST`, `GET`, `DELETE`, `PUT`
표현 (Representations)	자원에 대한 행위의 내용 (Body)	HTTP Message Payload (JSON, XML, TEXT 등)	`{ "member-id": "1234", "member-name": "이성민",}`

REST API 설계 기본 규칙 (중요)

1) URI는 정보의 자원을 표현해야 한다.

자원을 표현할 때는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
단일 자원을 나타내는 문서 이름으로는 단수 명사를 사용해야 한다.
자원의 집합을 나타내는 컬렉션 이름으로는 복수 명사를 사용해야 한다.
자원의 저장소 이름으로는 복수 명사를 사용해야 한다.
잘못된 예시:
GET /Product/5
올바른 예시:
GET /products/5

2) 자원에 대한 행위는 HTTP 메서드(GET, PUT, POST, DELETE 등)로 표현한다.

URI에 HTTP 메서드를 포함해서는 안 된다.
- 잘못된 예시:
  GET /products/delete/15
- 올바른 예시:
  DELETE /products/15
URI에 CRUD 기능을 나타내는 동사를 사용해서는 안 된다.
- 잘못된 예시:
  GET /orders/show/42
  POST /orders/add/23
- 올바른 예시:
  GET /orders/42
  POST /orders
URI 경로 중 변하는 부분은 리소스를 식별하는 고유한 값으로 대체한다.
- 상품을 생성하는 경로:
  POST /items
- id가 7인 상품을 수정하는 경로:
  PUT /items/7
- id가 7인 상품을 삭제하는 경로:
  DELETE /items/7

REST API 표시 규칙 (중요)

슬래시 구분자(/ )는 계층 관계를 나타내는데 사용한다.
URI 마지막 문자로 슬래시(/ )를 포함하지 않는다.
하이픈(-)은 URI 가독성을 높이는데 사용
밑줄(_)은 URI에 사용하지 않는다.
URI 경로에는 소문자가 적합하다.

파일확장자는 URI에 포함하지 않는다.
Accept header를 사용한다.

- 잘못된 예시:
	http://restapi.example.com/documents/2023/report.pdf (X)
- 올바른 예시:
	GET /documents/2023/report HTTP/1.1
	Host: restapi.example.com
	Accept: application/pdf (O)