팀 프로젝트를 진행할 때마다 팀원들이 각자 생각하는 API 설계 규칙이 달라서, 매번 새로운 회의를 하고 규칙을 작성하는 것이 번거롭고 시간 낭비가 되었습니다.
이런 답답한 상황에서 팀원 모두를 설득할 수 있을 만큼 완벽한 RESTful API 설계 규칙을 만들기 위해 많은 노력을 기울였습니다!!!
덕분에 팀원들을 설득하여 프로젝트를 빠르게 진행할 수 있었습니다. 원래 노션에 작성해두었던 이 문서를 다른 사람들에게도 도움이 될까 하여 블로그에 올려보게 되었습니다 :)
1. 자원(리소스) 기반 URI
일관된 URI 구조: 모든 자원은 고유한 URI를 가짐. 자원은 간결하고 명확하게 식별되어야 합니다.
URL 설계 규칙
마지막에 / 포함하지 않기:
예:
http://api.test.com/users
_(underbar) 대신 -(dash) 사용:
예:
http://api.test.com/users/post-comments
소문자 사용:
예:
http://api.test.com/users/post-comments
URL에 행위(method) 포함하지 않기:
예: DELETE
http://api.test.com/users/1/posts/1
컨트롤 자원을 의미하는 URL에는 동사 허용:
예:
http://api.test.com/posts/duplicate
Restful API 설계 모범 사례
추가적인 PathVariable 및 QueryString 사용 예시
PathVariable과 QueryString
PathVariable
정의:
PathVariable은 URL의 경로에 포함되는 변수를 의미합니다. 일반적으로 리소스의 식별자나 주요 속성을 나타내는 데 사용됩니다.적합한 상황:
특정 리소스 식별: 특정 리소스에 직접 접근할 때 사용합니다. 예를 들어,
/users/{id}에서{id}는 특정 사용자의 고유 식별자
입니다.
리소스 계층 표현: 부모-자식 관계나 계층적 구조를 표현할 때 유용합니다. 예:
/users/{id}/posts는 특정 사용자의 모든 포스트를 나타냅니다.장점:
URL 경로의 일부로서 직관적이고 명확하게 특정 리소스를 지목합니다.
계층적이고 구조적인 URL을 만들 수 있어 API의 가독성이 향상됩니다.
QueryString
정의:
QueryString은 URL의?뒤에 오는 키-값 쌍의 집합입니다. 주로 옵션, 필터링, 정렬 또는 검색 조건 등을 지정하는 데 사용됩니다.적합한 상황:
데이터 필터링: 특정 기준에 따라 데이터를 필터링할 때 사용합니다. 예:
/products?category=books&price_below=20정보 정렬: 데이터를 특정 순서로 정렬해야 할 때 사용합니다. 예:
/posts?sort_by=date&order=asc검색 조건 적용: 키워드나 다양한 파라미터로 데이터를 검색할 때 유용합니다. 예:
/users?name=John
장점:
URL 경로가 아닌 파라미터를 통해 유연한 데이터 조작과 검색을 할 수 있습니다.
다양한 파라미터 조합을 통해 복잡한 쿼리와 데이터 요청을 간편하게 처리할 수 있습니다.
2. HTTP 동사 활용
HTTP 프로토콜은 다양한 동사(메서드)를 제공합니다. RESTful API 설계에서는 이러한 동사를 적절하게 활용하여 API의 의도를 명확하게 전달해야 합니다.
GET: 리소스의 정보를 조회하기 위해 사용합니다.POST: 리소스를 생성하기 위해 사용합니다.PUT: 리소스의 정보를 업데이트하기 위해 사용합니다.DELETE: 리소스를 삭제하기 위해 사용합니다.PATCH: 리소스의 일부분을 업데이트하기 위해 사용합니다.
3. 적절한 상태 코드 반환
HTTP 상태 코드는 API의 응답에 포함되어 클라이언트에게 작업 결과를 알려줍니다. RESTful API 설계에서는 적절한 상태 코드를 반환하여 클라이언트가 요청에 대해 올바르게 대응할 수 있도록 해야 합니다. 일반적으로 사용되는 몇 가지 상태 코드는 다음과 같습니다:
200 OK: 성공적인 GET, PUT, PATCH 요청.
201 Created: 성공적인 POST 요청.
204 No Content: 성공적인 DELETE 요청.
400 Bad Request: 잘못된 요청 형식.
401 Unauthorized: 인증되지 않은 접근.
403 Forbidden: 권한 없는 접근.
404 Not Found: 요청한 리소스가 없음.
500 Internal Server Error: 서버 내부 오류.
4. 적절한 데이터 포맷
모든 요청과 응답은 JSON 형태로 주고받습니다.
예시 요청/응답 데이터 포맷:
요청:
{ "title": "The Great Gatsby" }응답:
{ "id": 3, "title": "The Great Gatsby" }
5. 적절한 인증과 권한 부여
인증 방식은 API 키, OAuth, JWT 등을 활용합니다.
모든 API 요청은 적절한 인증 토큰과 함께 전송되어야 합니다.
참고문헌
