들어가며
이번에 반려동물을 위한 쇼핑몰을 제작하는 프로젝트에서 backend를 맡게 되었습니다. 제가 RESTful API 설계를 하게 되면서, 이전 미니 프로젝트에서 정리해뒀던 RESTful API 원칙에 대한 정리와 이번에 설계한 URI를 간단하게 공유하려고 합니다.
RESTful API란?
REST란 Representational State Transfer의 약자로 지금으로부터 약 20여년 전에 생긴 개념입니다. REST의 의미는 직역하면 분산 시스템을 위한 아키텍처 스타일인데 말이 조금 어렵습니다. 조금 더 와닿게 설명한다면 그냥 웹 서비스가 데이터를 주고 받는 방법 중 하나입니다. 그리고 RESTful API는 그냥 REST한 원칙을 따르는 API라는 의미입니다. RESTful API의 원론적인 이야기는 이쯤에서 넘어가고 왜 RESTful API를 적용하는지 이유를 알아보겠습니다.
RESTful API의 장점
- 일관성 : URL과 메서드가 항상 같은 방식으로 동작하기 때문에 API를 사용할 때 헷갈리지 않음
- 확장성 : 자원과 작업을 구분해두면 나중에 자원을 추가하거나 기능을 확장하기 용이
- 유지보수성 : 규칙이 명확해 다른 개발자가 봤을 때도 쉽게 이해하고 수정 가능
그럼 REST스러운 API를 설계할 때 어떤 규칙을 따라는 것일까요? 이제 RESTful API의 규칙, URI 설계 시 주의점, HTTP 응답 상태 코드에 대해 알아보겠습니다.
RESTful API 규칙
1. URI는 정보의 자원(resource)을 표현
자원은 API로 식별하고 조작할 수 있는 엔티티이기 때문에 반드시 명사를 사용해야 합니다. 또한 컬렉션을 표시하려면 단수가 아닌 명사의 복수형(-s)을 사용하면 됩니다. (컬렉션은 users, posts, products처럼 여러 자원들을 그룹으로 묶은것을 말합니다.)
2. 자원(resource)에 대한 행위는 HTTP Method로만 표현
자원에 대한 행위에 해당하는 HTTP Method가 있기 때문에 URI에 굳이 get, delete 같은 키워드는 사용할 필요가 없습니다.
GET /api/v1/users/get/me (X)
GET /api/v1/users/me (O)첫번째 URI는 REST스럽지 못한 예시입니다. URI에 자원에 대한 행위는 HTTP Method에 이미 포함되어 있기 때문에 굳이 URI에도 포함시켜서 복잡성을 늘릴 필요가 없습니다. 따라서 두번째 URI가 RESTful API의 옳은 예시라고 할 수 있습니다.
RESTful API의 URI 설계 시 주의점
1. 슬래시 구분자는 계층 관계를 표현
URI에서 슬래시를 이용해 자원 간의 계층 관계를 표현할 수 있습니다.
GET /users/{userId}/orders/{orderId}2. URI 마지막에 슬래시 구분자 포함 금지
일관성 유지를 위해 마지막에는 슬래시를 포함하지 않습니다.
GET /api/v1/users/me/ (X)
GET /api/v1/users/me (O)3. 언더바(_) 대신 하이픈(-) 사용
언더바를 사용하면 문자가 가려지는 등 보기 힘든 경우가 발생하기 때문에 하이픈 사용을 더 권장합니다. 다만, 하이픈도 되도록이면 사용하지 않는 것이 더 좋습니다.
GET /api/v1/user-profile (O)
GET /api/v1/user_profile (X)예시를 들기 위해 위처럼 작성했지만 user-profile도 REST와 거리가 있는 방식입니다.
4. URI 경로는 항상 소문자로 작성
대·소문자에 따라 다른 리소스로 인식하는 경우가 존재하기 때문에 소문자만 사용해서 일관성을 유지합니다.
5. 쿼리 파라미터를 사용해 데이터 필터링, 정렬, 페이징
파라미터의 이름은 목적과 기능을 나타내는 설명적이고 일관된 이름을 사용해야합니다.
GET /users?q=John&f=25&o=asc&l=2 (X)
GET /users?name=John&age=25&sort=asc&page=2 (O)첫번째 URI는 각각의 파라미터가 무슨 의미인지 쉽게 파악하기가 어렵습니다. 따라서 두번째 URI처럼 목적을 명확하게 나타내는 이름을 사용해야 RESTful API 설계입니다.
6. 리소스에 대한 작업은 예외적으로 동사를 허용
RESTful API에서 URI는 일반적으로 명사로 리소스를 나타냅니다. 하지만, 리소스에 대한 특정 작업을 표현할 때는 예외적으로 동사를 사용할 수 있습니다.
/users/{userId}/activate (사용자 활성화 작업)
/orders/{orderId}/cancel (주문 취소 작업)7. 파일 확장자는 포함하지 않음
RESTful API에서 URI는 리소스를 표현하는 것이므로, URI에 파일 확장자를 포함하지 않는 것이 좋습니다. 대신, Accept 헤더를 사용하여 클라이언트가 원하는 응답 형식을 지정할 수 있습니다.
8. 응답 시 의미에 맞는 HTTP 상태 코드를 반드시 반환
RESTful API에서 올바른 HTTP 상태 코드를 반환하는 것은 클라이언트와 서버 간의 명확한 소통을 위해 매우 중요합니다. 클라이언트는 상태 코드에 따라 다음 동작을 결정하므로, 의미에 맞는 상태 코드를 반환하는 것은 REST API의 핵심적인 원칙 중 하나입니다.
HTTP 응답 상태 코드
1. 2XX
| 200 | 클라이언트의 요청을 정상적으로 수행함 |
| 201 | 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨 |
2. 4XX
| 400 | 클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드 |
| 401 | 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 |
| 403 | 유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 |
| 405 | 클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드 |
3. 5XX
| 500 | 서버에 문제가 있을 경우 사용하는 응답 코드 |
RESTful API 설계 예시
아래는 제가 이번 프로젝트에서 설계한 API입니다!
.
.
.
마치며
RESTful API 원칙들은 어느 블로그를 찾아봐도 내용이 전부 같았습니다. 하지만 처음 공부할 땐 대부분의 블로그가 RESTful API의 원칙들에 대해 나열만 하고 정확한 설명이 없어서 배우는데 힘들었습니다. RESTful API 개념을 처음 접하는 분들도 최대한 와닿을 수 있게 설명을 해봤는데 조금이나마 도움이 되었으면 합니다.
저는 이번 endpoint 설계가 두번째인데 다른분들도 그냥 프로젝트 하다보면 RESTful API 설계는 금방 익히고 적용할 수 있을거라고 생각합니다! 다음달 중순에 또 새로운 프로젝트를 시작하는데 그때도 가능하다면 제가 endpoint 설계를 담당해서 다시 글을 작성해보도록 하겠습니다!
피드백이나 질문은 언제나 환영합니다! 😊