팀 프로젝트를 진행할 때마다 팀원들이 각자 생각하는 API 설계 규칙이 달라서, 매번 새로운 회의를 하고 규칙을 작성하는 것이 번거롭고 시간 낭비가 되었습니다.이런 답답한 상황에서 팀원 모두를 설득할 수 있을 만큼 완벽한 RESTful API 설계 규칙을 만들기 위해 많은 노력을 기울였습니다!!!덕분에 팀원들을 설득하여 프로젝트를 빠르게 진행할 수 있었습니다. 원래 노션에 작성해두었던 이 문서를 다른 사람들에게도 도움이 될까 하여 블로그에 올려보게 되었습니다 :)<h2>1. 자원(리소스) 기반 URI</h2><ul class="tight" data-tight="true"><li>일관된 URI 구조: 모든 자원은 고유한 URI를 가짐. 자원은 간결하고 명확하게 식별되어야 합니다.</li></ul><h3>URL 설계 규칙</h3><ul class="tight" data-tight="true"><li>마지막에 / 포함하지 않기:<ul class="tight" data-tight="true"><li>예: <code spellcheck="false">http://api.test.com/users</code></li></ul></li><li>_(underbar) 대신 -(dash) 사용:<ul class="tight" data-tight="true"><li>예: <code spellcheck="false">http://api.test.com/users/post-comments</code></li></ul></li><li>소문자 사용:<ul class="tight" data-tight="true"><li>예: <code spellcheck="false">http://api.test.com/users/post-comments</code></li></ul></li><li>URL에 행위(method) 포함하지 않기:<ul class="tight" data-tight="true"><li>예: DELETE <code spellcheck="false">http://api.test.com/users/1/posts/1</code></li></ul></li><li>컨트롤 자원을 의미하는 URL에는 동사 허용:<ul class="tight" data-tight="true"><li>예: <code spellcheck="false">http://api.test.com/posts/duplicate</code></li></ul></li></ul><hr><h2>Restful API 설계 모범 사례</h2><img src="https://image.until.blog/thingk0/article/1718791191412" alt="until-599"><img src="https://image.until.blog/thingk0/article/1718791228436" alt="until-600"><img src="https://image.until.blog/thingk0/article/1718791344586" alt="until-601"><img src="https://image.until.blog/thingk0/article/1718791581052" alt="until-602"><img src="https://image.until.blog/thingk0/article/1718791600715" alt="until-603"><img src="https://image.until.blog/thingk0/article/1718791633327" alt="until-604"><img src="https://image.until.blog/thingk0/article/1718791656507" alt="until-605"><img src="https://image.until.blog/thingk0/article/1718791687549" alt="until-606"><h3>추가적인 PathVariable 및 QueryString 사용 예시</h3><img src="https://image.until.blog/thingk0/article/1718791707307" alt="until-607"><h3>PathVariable과 QueryString</h3><hr><h3>PathVariable</h3><ul class="tight" data-tight="true"><li>정의: <code spellcheck="false">PathVariable</code>은 URL의 경로에 포함되는 변수를 의미합니다. 일반적으로 리소스의 식별자나 주요 속성을 나타내는 데 사용됩니다.</li><li>적합한 상황:<ul class="tight" data-tight="true"><li>특정 리소스 식별: 특정 리소스에 직접 접근할 때 사용합니다. 예를 들어, <code spellcheck="false">/users/{id}</code>에서 <code spellcheck="false">{id}</code>는 특정 사용자의 고유 식별자</li></ul></li></ul>입니다.<ul class="tight" data-tight="true"><li>리소스 계층 표현: 부모-자식 관계나 계층적 구조를 표현할 때 유용합니다. 예: <code spellcheck="false">/users/{id}/posts</code>는 특정 사용자의 모든 포스트를 나타냅니다.</li><li>장점:<ul class="tight" data-tight="true"><li>URL 경로의 일부로서 직관적이고 명확하게 특정 리소스를 지목합니다.</li><li>계층적이고 구조적인 URL을 만들 수 있어 API의 가독성이 향상됩니다.</li></ul></li></ul><h3>QueryString</h3><ul class="tight" data-tight="true"><li>정의: <code spellcheck="false">QueryString</code>은 URL의 <code spellcheck="false">?</code> 뒤에 오는 키-값 쌍의 집합입니다. 주로 옵션, 필터링, 정렬 또는 검색 조건 등을 지정하는 데 사용됩니다.</li><li>적합한 상황:<ul class="tight" data-tight="true"><li>데이터 필터링: 특정 기준에 따라 데이터를 필터링할 때 사용합니다. 예: <code spellcheck="false">/products?category=books&amp;price_below=20</code></li><li>정보 정렬: 데이터를 특정 순서로 정렬해야 할 때 사용합니다. 예: <code spellcheck="false">/posts?sort_by=date&amp;order=asc</code></li><li>검색 조건 적용: 키워드나 다양한 파라미터로 데이터를 검색할 때 유용합니다. 예: <code spellcheck="false">/users?name=John</code></li></ul></li><li>장점:<ul class="tight" data-tight="true"><li>URL 경로가 아닌 파라미터를 통해 유연한 데이터 조작과 검색을 할 수 있습니다.</li><li>다양한 파라미터 조합을 통해 복잡한 쿼리와 데이터 요청을 간편하게 처리할 수 있습니다.</li></ul></li></ul><hr><h2>2. HTTP 동사 활용</h2>HTTP 프로토콜은 다양한 동사(메서드)를 제공합니다. RESTful API 설계에서는 이러한 동사를 적절하게 활용하여 API의 의도를 명확하게 전달해야 합니다.<ul class="tight" data-tight="true"><li><code spellcheck="false">GET</code>: 리소스의 정보를 조회하기 위해 사용합니다.</li><li><code spellcheck="false">POST</code>: 리소스를 생성하기 위해 사용합니다.</li><li><code spellcheck="false">PUT</code>: 리소스의 정보를 업데이트하기 위해 사용합니다.</li><li><code spellcheck="false">DELETE</code>: 리소스를 삭제하기 위해 사용합니다.</li><li><code spellcheck="false">PATCH</code>: 리소스의 일부분을 업데이트하기 위해 사용합니다.</li></ul><hr><h2>3. 적절한 상태 코드 반환</h2>HTTP 상태 코드는 API의 응답에 포함되어 클라이언트에게 작업 결과를 알려줍니다. RESTful API 설계에서는 적절한 상태 코드를 반환하여 클라이언트가 요청에 대해 올바르게 대응할 수 있도록 해야 합니다. 일반적으로 사용되는 몇 가지 상태 코드는 다음과 같습니다:<ul class="tight" data-tight="true"><li>200 OK: 성공적인 GET, PUT, PATCH 요청.</li><li>201 Created: 성공적인 POST 요청.</li><li>204 No Content: 성공적인 DELETE 요청.</li><li>400 Bad Request: 잘못된 요청 형식.</li><li>401 Unauthorized: 인증되지 않은 접근.</li><li>403 Forbidden: 권한 없는 접근.</li><li>404 Not Found: 요청한 리소스가 없음.</li><li>500 Internal Server Error: 서버 내부 오류.</li></ul><hr><h2>4. 적절한 데이터 포맷</h2>모든 요청과 응답은 JSON 형태로 주고받습니다.<ul class="tight" data-tight="true"><li>예시 요청/응답 데이터 포맷:<ul class="tight" data-tight="true"><li>요청: <code spellcheck="false">{ "title": "The Great Gatsby" }</code></li><li>응답: <code spellcheck="false">{ "id": 3, "title": "The Great Gatsby" }</code></li></ul></li></ul><hr><h2>5. 적절한 인증과 권한 부여</h2>인증 방식은 API 키, OAuth, JWT 등을 활용합니다.<ul class="tight" data-tight="true"><li>모든 API 요청은 적절한 인증 토큰과 함께 전송되어야 합니다.</li></ul><hr><h3>참고문헌</h3><ul class="tight" data-tight="true"><li><a target="_blank" rel="noopener noreferrer nofollow" href="https://velog.io/@tiger/API-RESTful-API">https://velog.io/@tiger/API-RESTful-API</a></li><li><a target="_blank" rel="noopener noreferrer nofollow" href="https://library.gabia.com/contents/8339/">https://library.gabia.com/contents/8339/</a></li><li><a target="_blank" rel="noopener noreferrer nofollow" href="https://medium.com/tech-pentasecurity/restful-api-%EB%84%A4%EC%9D%B4%EB%B0%8D-7c81bdb9da63">https://medium.com/tech-pentasecurity/restful-api-네이밍-7c81bdb9da63</a></li><li><a target="_blank" rel="noopener noreferrer nofollow" href="https://velog.io/@gun_123/RESTful-API-%EC%84%A4%EA%B3%84-%EC%9B%90%EC%B9%99%EA%B3%BC-%EC%98%88%EC%8B%9C">https://velog.io/@gun_123/RESTful-API-설계-원칙과-예시</a></li></ul><img src="https://image.until.blog/thingk0/article/1718793846972" alt="until-613">

원래 혼자서만 몰래 보려고 만든 문서였지만, 다른 사람들에게도 도움이 되고자 그동안 제가 나름대로 정리해서 만든 RESTful API 설계 규칙입니다!!

안녕하세요