REST API 디자인 리팩토링

seonjeong·2023년 11월 26일

Network

목록 보기

10/10

HTTP 강의를 듣고 나서, 기존에 디자인한 API가 RESTful하지 않다고 느껴졌다.

이를 개선하고 높은 품질의 API를 구축하기 위해 REST API 주요 설계 원칙과 네이밍 규칙에 대한 개념을 재정립하고 API를 다시 설계하는 시간을 가져보기로 했다.

❤️ REST API란?

REST란 "Representational State Transfer"의 약자이다.

자원을 자원(resource)의 표현(representation) 으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다.

REST의 기본 원칙을 성실히 지킨 서비스 디자인을 "RESTful"이라고 표현한다.

즉, REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처이고, REST API는 REST를 기반으로 서비스 API를 구현한 것을 의미한다.

❤️ REST API 주요 설계 원칙

1. URI는 리소스를 표현해야 한다

URI 설계 시 가장 중요한 것은 리소스 식별이다. 리소스를 식별할 수 있는 이름은 동사보다는 명사를 사용한다

# bad
GET /getTodos/1
GET /todos/show/1

# good
GET /todos/1

2. 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다

리소스에 대한 행위는 HTTP 요청 메서드로 표현하며 URI에 표현하지 않는다

# bad
GET /todos/delete/1

# good
DELETE /todos/1

HTTP 메서드에 관해서는 모든 개발자를 위한 HTTP 웹 기본 지식(4) - HTTP 메서드 및 활용 참고

❤️ REST API 네이밍 규칙

1. 리소스를 표현하기 위해 명사를 사용해라

RESTful URI는 동사가 아닌 명사로 리소스를 나타내야 한다.

더 명확하게 하기 위해, 리소스의 원형을 세 가지 범주(문서, 수집, 저장)로 나눌 수 있다.
항상 리소스가 어디에 해당하는지 확인 하고, 알맞은 네이밍 컨벤션을 일관성있게 사용한다.

문서(document)

단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)

단수형 이름 사용
예시) device-management, user-management

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

컬렉션(collection)

서버가 관리하는 리소스 디렉토리
서버가 리소스의 URI를 생성하고 관리

복수형 이름 사용
예시) managed-devices, users

/device-management/managed-devices
/user-management/users
/user-management/users/{id}/accounts

스토어(store)

클라이언트가 관리하는 자원 저장소
클라이언트가 리소스의 URI를 알고 관리
복수형 이름 사용
예시) playlists
```
/song-management/users/{id}/playlists
```

컨트롤러(controller), 컨트롤 URI

문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행

동사를 직접 사용
예시) /members/{id}/new

2. 일관성이 핵심이다

일관된 리소스 네이밍 컨벤션과 URI 형식을 사용한다.

2-1. 계층 관계를 나타내기 위해 '`/`' 를 사용하라

/device-management
/device-management/managed-devices
/device-management/managed-devices/{id}
/device-management/managed-devices/{id}/scripts
/device-management/managed-devices/{id}/scripts/{id}

2-2. URI 마지막에 '`/`' 를 사용하지 마라

http://api.example.com/device-management/managed-devices/ ❌
http://api.example.com/device-management/managed-devices

2-3. URI 가독성을 높이기 위해 '`-`'을 사용하라

//More readable
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  

//Less readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation

2-4. '`_`' 를 사용하지 마라

//More readable
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location 

//More error prone
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location

2-5. 소문자를 사용하라

아래의 예에서 1과 2는 동일하지만 3은 같지 않다.
HOST에서는 대소문자 구별이 없고, 이 외에는 대소문자가 구별되기 때문이다.

http://api.example.org/my-folder/my-doc       //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc       //2
http://api.example.org/My-Folder/my-doc       //3

3. 파일 확장자를 사용하지 마라

파일 확장자는 가독성도 안좋고 어떤 장점도 없다

/device-management/managed-devices.xml  /*Do not use it*/

/device-management/managed-devices 	/*This is correct URI*/

4. CRUD 함수명을 사용하지 마라

URI는 리소스를 식별하는 데만 사용되어야 하며 어떤 CRUD 기능이 수행되는지는 HTTP 요청 메서드로 표현해야 한다.

HTTP GET /device-management/managed-devices  			//Get all devices
HTTP POST /device-management/managed-devices  			//Create new Device

HTTP GET /device-management/managed-devices/{id}  		//Get device for given Id
HTTP PUT /device-management/managed-devices/{id}  		//Update device for given Id
HTTP DELETE /device-management/managed-devices/{id}  	//Delete device for given Id

5. URI 컬렉션을 필터링하기 위해 쿼리 파라미터를 사용하라

종종, 특정 리소스 특성에 따라 정렬되고, 필터링되고, 제한된 리소스의 컬렉션이 필요한 요구가 발생한다.

이러한 요구에서는, 새로운 API를 생성하지 않고, 쿼리 파라미터를 활용한다.

/device-management/managed-devices
/device-management/managed-devices?region=USA
/device-management/managed-devices?region=USA&brand=XYZ
/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

REST API URI Naming Conventions and Best Practices 참고