이번에 일정관리 앱 프로젝트를 시작하면서 첫 단계로 API 명세서와 ERD를 작성해보았다.
API 명세서는 어떻게 작성해야 할까?
우선 API 명세서는 API가 어떤 용도로 만들어졌는지, 어떤 요청 방식을 사용하는지 등을 설명하는 설명서라고 이해하면 될 것 같다. 제 3자가 이용할 때 이해하기 쉽게 디테일하게 적어줄 수록 좋을 것 같다.
Example
일정을 조회, 추가하는 상황을 예로 들어보자.
| 기능 | Method | URL | request | response | 상태코드 |
|---|---|---|---|---|---|
| 일정 조회 | GET | api/schedules:id | param:id(INT) | {"Schedule [{"user_id": 1, "schedule_id":1, "title": "미용실 가기"}]"} | Sucess:400, Fail: 500 |
| 일정 생성 | POST | api/schedules:id | body:user_id(INT), schedule_id(INT), title(VARCHAR) | {"Message": "일정이 생성되었습니다."} | Sucess:400, Fail: 500 |
- 어떠한 기능이 있으며 어떤 방식으로 요청하고 응답을 받는지 예시 데이터나 상태코드를 작성해줄 수 있다.
- API 명세서 작성을 도와주는 다양한 Tool들이 있다. Swagger, Postman 등을 이용하면 가독성 좋게 내용을 깔끔하게 정리할 수 있다.
Postman을 이용한 API 명세서
https://documenter.getpostman.com/view/39349960/2sAY4vfMuy
Postman에서 API 테스트 기능과 동시에 내가 만든 API를 명세서로 볼 수 있는 기능이 제공된다.
ERD
ERD(Entity-Relationshop Diagram)는 데이터베이스의 구조를 시각적으로 표현하는 다이어그램이다. 데이터베이스의 개체(Entity), 속성(Attribute), 관계(Relationshop)를 그림으로 나타낸 것.
ERD를 사용하면 데이터베이스 구조를 한눈에 파악하고 이해하기 수월하다.
- Entity: 저장할 데이터의 주체를 의미하며, 테이블에 대응된다.
- ex)고객, 주문, 제품 등. 각 Entity는 고유한 이름과 여러 속성을 가진다.
- Attribute: Entity의 특성을 나타내는 요소로, 데이터베이스의 열(column)과 유사하다.
- ex)고객 Entity의 경우 이름, 주소, 전화번호 등이 Attribute가 될 수 있다.
- Relationship: Entity 간의 상호작용을 나타낸다. 관계는 1:1, 1:N, N:M 형태로 나타낼수 있으며, 두 Entity가 어떻게 연결되는지를 표현한다.
- ERD 작성 Tool
- ERD Cloud: https://www.erdcloud.com/
