API 명세서

팀프로젝트를 진행하면서 팀원들과 기획부터 ERD작성, API 명세서를 작성하면서 공부한 내용을 정리해봄.

API 명세서는 일반적으로 기획서와 ERD에 기반하여 작성하는 것이 좋은것 같다.

1. 순수 도메인 중심 설계: API는 데이터 모델과 비즈니스 로직에 기반하여 설계되므로, ERD와 같은 순수 도메인 구조를 이해하고 정의하는 것이 중요함. 이를 통해 각 엔티티의 관계와 역할이 명확해지고, 필요한 엔드포인트나 요청 파라미터 등이 잘 정의될 수 있음.

엔드포인트(Endpoint)는 API에서 클라이언트가 특정 작업을 요청할 수 있는 URL 경로를 의미. 쉽게 말해, 엔드포인트는 서버와 클라이언트가 통신하는 접점입니다. 클라이언트는 엔드포인트에 HTTP 요청을 보내고, 서버는 요청을 처리해 응답을 반환합니다.

엔드포인트의 구성 요소

엔드포인트는 보통 다음과 같은 요소로 구성됩니다.

1. HTTP 메서드: 요청의 목적을 나타내며, 주로 GET, POST, PUT, DELETE와 같은 메서드를 사용.

   • GET은 데이터 조회용
   • POST는 데이터 생성용
   • PUT은 데이터 수정용
   • DELETE는 데이터 삭제용

2. URL 경로: API가 제공하는 리소스의 위치를 나타내는 경로입니다. 예를 들어, /api/users는 "users"라는 사용자 정보를 조회하거나 관리하는 경로일 수 있음.

3. 경로 매개변수와 쿼리 매개변수:

   • 경로 매개변수: /api/users/{id}처럼 특정 리소스를 식별하기 위해 URL 경로에 포함되는 변수입니다.
   • 쿼리 매개변수: /api/posts?sort=createdAt&order=desc처럼 추가적인 필터링이나 정렬 기준을 전달하는 데 사용됨.

예시

예를 들어, 사용자를 조회하는 API의 엔드포인트가 다음과 같을 수 있음:

• URL: /api/users/123
• HTTP 메서드: GET

여기서 /api/users/123는 ID가 123인 사용자의 정보를 조회하는 엔드포인트예요. 클라이언트가 이 엔드포인트로 GET 요청을 보내면, 서버는 ID가 123인 사용자 정보를 반환하게 됩니다.

API 명세서에는 이러한 엔드포인트의 목록과 각각의 요청 및 응답 형식, 요청에 필요한 데이터 등이 상세히 포함되어, 개발자들이 클라이언트와 서버 간의 통신 방식을 명확하게 이해할 수 있도록 함.

2. 기획서 기반: 기획서는 기능 요구사항을 명확하게 담고 있음. API 명세서는 이 기능을 구현하기 위한 엔드포인트, HTTP 메서드, 요청/응답 형식, 상태 코드 등을 포함해야 하므로, 기획서를 중심으로 필요한 기능을 우선적으로 고려. 이렇게 하면 기획서의 기능들이 API 명세서에 잘 반영될 수 있음.

3. 와이어프레임은 보조 역할: 와이어프레임은 UI 중심의 설계이므로, API 설계에 직접적인 영향을 미치기보다는 보조적인 참고 자료로 쓰자. 와이어프레임에서 필요한 데이터나 화면 전환 등이 API에 반영될 수 있지만, 와이어프레임만을 기준으로 API를 설계하면 도메인 모델과 불일치할 위험이 있음.

따라서 ERD를 먼저 작성하고, 기획서의 기능 요구사항을 토대로 API 명세서를 작성한 후, 와이어프레임을 보조 자료로 활용하는 것이 좋은 접근임.

참고

---

여행족 프로젝트의 Restful API 예)
api/v1/posts/{postId}/reviews/{reviewId}는 RESTful한 설계를 잘 따른 API라고 볼 수 있음. 각 경로는 리소스의 계층적 구조를 나타내며, 의미상으로도 분명하기 때문입니다. 이 API는 특정 postId에 속한 특정 reviewId를 조회한다는 의미를 명확히 전달합니다.

1. 계층적 관계 표현: posts와 reviews는 부모-자식 관계로, 특정 게시물에 대한 특정 후기를 조회하는 경우, URL 경로에서 부모 리소스(posts/{postId})에 자식 리소스(reviews/{reviewId})를 포함하여 계층적 구조를 표현합니다.

2. 리소스에 대한 접근: 각 경로는 고유한 리소스에 접근하는 경로로, GET 메서드를 사용하여 해당 경로에 요청을 보내면 reviewId에 해당하는 후기를 조회할 수 있다는 의미를 전달합니다.

3. 명확한 리소스 식별: postId와 reviewId를 통해 특정 리소스를 명확히 식별할 수 있어 RESTful 설계 원칙을 잘 따르고 있습니다.

따라서 후기 조회 API로서도 RESTful한 설계를 잘 반영한 구조라고 할 수 있음.

---

참고: 팀원들과 ERD를 작성하면서 나는 기획서의 내용을 이해하기도 버거웠다.
팀원중 한분이 SI에서 3년정도 일하신 분인데 거의 이분이 ERD 설계부분을 리드하셨다. 그래서 그분께 여쭤보니 경험이 많아서 그렇다고 하셨다. 다른 방법이 또 있을지 궁금해서 GPT에게 ERD를 어떻게 하면 잘 작성 할 수 있는지 물어봤다.

ChatGPT

ERD 설계는 처음에는 어려울 수 있지만, 반드시 경험자들만의 전유물은 아니며 충분히 학습과 연습으로 실력을 키울 수 있는 영역이에요. 초보자가 기획서를 보고 ERD를 설계하기 어려운 이유는 기획서의 요구사항을 데이터 모델로 추상화하는 과정이 생소할 수 있기 때문입니다.

ERD 설계를 잘 하기 위한 몇 가지 팁을 드릴게요:

1. 요구사항을 데이터 관점에서 분석하기: 기획서를 읽을 때 기능에 대한 요구사항을 그대로 데이터 모델에 연결시키기보다는, "이 기능에 필요한 핵심 정보는 무엇인가?"라는 질문을 던지면서 필요한 엔티티(테이블)를 떠올려 보는 게 중요해요. 예를 들어, "게시판 기능이 있다"면 게시글, 사용자, 댓글 같은 엔티티가 필요할 수 있겠죠.

2. 주요 엔티티와 관계 정의하기: 처음에는 핵심 엔티티만 잡고, 엔티티 간의 관계를 정의해 봅니다. 예를 들어, 게시글과 사용자는 작성자 관계가 있고, 게시글과 댓글은 1:N 관계로 연결되겠죠.

3. 작은 ERD부터 시작: 모든 기능을 한꺼번에 ERD로 표현하려 하면 어렵기 때문에, 기능 단위로 쪼개서 ERD를 조금씩 그려보고 확장해 가는 것도 좋은 방법이에요.

4. 다른 프로젝트의 ERD 예시 참고하기: 경험이 부족할 때는 유사한 프로젝트나 실제 서비스의 ERD 예시를 보는 것이 도움이 됩니다. 그 구조를 보며 어떻게 데이터를 모델링했는지 참고하고, 반복 연습하면서 익숙해질 수 있어요.

경험이 많을수록 더 빨리 잘할 수 있지만, 초보자도 차근차근 경험을 쌓아가면서 점점 실력을 키울 수 있는 부분이에요.