REST API에서 URL을 작성하는 규칙

 

혼자 프로젝트를 할 땐 REST API URL을 단순히 이해하기 쉽게 작성하면 되겠지만, 다른 개발자들과 협업할 때는 공통된 규칙이 있어야합니다. 개발자 뿐만아니라 비개발자분들도 한 눈에 의미 파악이 가능하도록 작성하는 것이 중요합니다. 

자원 표현 (복수형)

REST API에서 URL은 자원을 표현해야 합니다. 예를 들어, 사용자 정보를 조회하는 API라면 /users와 같은 URL을 사용합니다.

 

동사보다 명사

동사보다는 명사를 사용합니다. CRUD(Create, Read, Update, Delete) 동작은 HTTP Method로 구분되기 때문에 URL에 동사를 사용하지 않습니다.

 

계층관계를 나타낼 때는 슬래시 구분자 사용

REST API에서 URL은 계층 구조를 갖도록 설계합니다. 예를 들어, 사용자 정보 중 특정 사용자의 정보를 조회하는 API라면 /users/{user_id}와 같은 URL을 사용합니다. 이렇게 하면 사용자 정보와 관련된 API가 /users 아래에 모여 있기 때문에 관리가 용이합니다.

소문자와 하이픈

소문자를 사용하고, 띄어쓰기 대신 하이픈(-)을 사용합니다. 예를 들어, 사용자 정보를 조회하는 API라면 /users/{user-id}와 같은 URL을 사용합니다.

파일 확장자 제거

REST API에서 URL에는 파일 확장자를 사용하지 않습니다. 예를 들어, 이미지 파일을 다운로드하는 API라면 /images/{image_id}와 같은 URL을 사용합니다.

나쁜 예:
http://api.project.com/students/3248234/courses/2005/fall.json
좋은 예:
http://api.project.com/students/3248234/courses/2005/fall

매개변수 전달

REST API에서 매개변수는 URL Query String이나 HTTP Body를 통해 전달합니다. 예를 들어, 사용자 정보를 생성하는 API라면 HTTP Body에 JSON 형식으로 사용자 정보를 전달합니다.

버전 관리

REST API에서는 API의 버전을 명시해야 합니다. 이를 통해 API의 변경 사항에 대한 호환성을 유지할 수 있습니다. 예를 들어, v1/users와 같은 URL을 사용하여 버전을 명시합니다.

 

URL 마지막엔 슬래시 구분자를 포함하지 않음

나쁜 예:
http://api.project.com/shapes/
좋은 예:
http://api.project.com/shapes

 

위의 규칙을 따르면 REST API의 URL을 보다 명확하고 일관성 있게 작성할 수 있습니다.

 

 

 

 

 

 

 

참고:

7 Rules for REST API URI Design