REST API Naming가이드

Caesars·2022년 2월 21일

어느날 팀원이 'uri 좀 rest api에 맞게 써라' 라고 하더군요. 여태까지 uri를 Camel Case로 작성하고 있었는데 알고 봤더니 rest api의 uri 작성 규칙이 그게 아니었던 것이었습니다. 그럼 지금까지 써왔던 'GET /member/getMemberList' 이런건 대체.. 뭐 지금부터라도 고쳐 나가야겠죠. 아주 세부적인 것까지 적어봤자 기억도 못할테니 중요한 몇몇 개념만 적어보겠습니다.

중심 규칙

uri는 명사로만 표현

URI는 자원을 표현하는데 중점을 둡니다. 동사는 사용하지 않습니다.

GET /device-management/get-device-management (X)
GET /device-management/managed-devices/ (0)

CRUD는 Method로 표현

자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현 합니다.

GET /device-management/managed-devices             //Get all devices
POST /device-management/managed-devices           //Create new Device
GET /device-management/managed-devices/{id}        //Get device for given Id
PUT /device-management/managed-devices/{id}        //Update device for given Id
DELETE /device-management/managed-devices/{id}    //Delete device for given Id

/(slash)로 계층간의 관계를 구분

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

/(slash)는 마지막 문자로 사용하지 않는다.

/device-management/managed-devices/ (X)
/device-management/managed-devices (0)

_(underbar) 대신 -(hyphens) 사용

를 구분자로 사용할 경우 보기 어렵거나 문자가 가려지기도 합니다. 이런 문제를 피하기 위해 _대신 -을 사용합니다.

/device-management/managed_devices/ (X)
/device-management/managed-devices (0)

uri는 소문자로 사용

보통 웹사이트에서 소문자를 사용하기 때문에 표준으로 사용하는듯 합니다.

/device-management/managed-Devices/ (X)
/device-management/managed-devices (0)

쿼리 파라미터는 camelCase 사용 가능

자원을 필터링하거나 정렬하거나 할 때 쿼리 파라미터를 사용합니다. 이 때는 링크와 파라미터를 구분하기 위해 camelCase가 사용 가능합니다.

/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

입력 Form으로 이동시에는?

자원을 가져오거나 할 때는 위의 가이드 대로 하면 되지만 새로 작성하거나 수정할 때 작성/수정 Form은 어떻게 제공할지에 대한 의문이 생깁니다.

답은 Form 자체도 정보로 취급해야 한다는 것입니다. 서버로부터 “새로운 아이템을 작성하기 위한 Form을 GET한다”고 생각하시면 됩니다.

HTTP Verb	Path	action	used for
GET	/photos	index	display a list of all photos
GET	/photos/new	new	return an HTML form for creating a new photo
POST	/photos	create	create a new photo
GET	/photos/:id	show	display a specific photo
GET	/photos/:id/edit	edit	return an HTML form for editing a photo
PUT	/photos/:id	update	update a specific photo
DELETE	/photos/:id	destroy	delete a specific photo