[API] RESTful을 적용한 API명세서 간단 정리

 

API(Application Programming Interface) 명세서는 API의 동작 방식과 사용 방법을 문서화한 것으로
클라이언트와 서버가 원활하게 통신할 수 있도록 돕는 역할을 한다.

 

 

1. API 명세서가 필요한 이유

• 개발자 간 소통 원활화 (백엔드 ↔ 프론트엔드)
• 일관된 API 설계 유지
• 유지보수 및 확장 용이
• API 테스트 및 디버깅 편의성 증가

---

 

2. RESTul API의 적용

• RESTful API는 예측 가능한 구조를 가지고 있어서 개발자가 API를 처음 봐도 직관적으로 사용 가능

POST /users → 사용자 생성

GET /users → 사용자 목록 조회

GET /users/{userId} → 특정 사용자 조회

PUT /users/{userId} → 사용자 정보 전체 수정

PATCH /users/{userId} -> 사용자 정보 일부 수정

DELETE /users/{userId} → 사용자 삭제

---

 

3. API 명세서 기본 양식

항목	설명
API 이름	API의 기능을 간략히 설명
요청 URL	API의 엔드포인트 주소
HTTP 메서드	GET, POST, PUT, DELETE 등 요청 방식
요청 헤더	인증 토큰, Content-Type 등의 정보
요청 파라미터	쿼리 또는 경로 변수 (필수 여부 포함)
요청 바디	JSON 등 요청 본문 (POST, PUT 요청 시)
응답 상태 코드	200(성공), 400(잘못된 요청), 500(서버 오류) 등
응답 예시	JSON 형태로 응답 데이터 제공
에러 코드	예외 발생 시 반환되는 코드와 메시지

---

 

4. 간단 예제

API 이름	HTTP	URL	요청 방식	요청 데이터	응답 데이터	응답 코드
일정 생성	POST	/api/schedules	body	{ "title": "제목", "contents": "내용" }	{ "id": 1, "title": "제목", "contents": "내용" }	201 Created
일정 전체 조회	GET	/api/schedules	-	-	[ { "id": 1, "title": "제목", "contents": "내용" }, { ... }, ... ]	200 OK
일정 단일 조회	GET	/api/schedules/{scheduleId}	Path Variable	scheduleId: 1	{ "id": 1, "title": "제목", "contents": "내용" }	200 OK / 404 Not Found
일정 전체 수정	PUT	/api/schedules/{scheduleId}	Path Variable, Body	scheduleId: 1, { "title": "제목", "contents": "내용" }	{ "id": 1, "title": "제목수정", "contents": "내용수정" }	200 OK / 404 Not Found
일정 부분 수정	PATCH	/api/schedules/{scheduleId}	Path Variable, Body	scheduleId: 1, { "title": "제목부분수정" }	{ "id": 1, "title": "제목부분수정", "contents": "내용" }	200 OK / 404 Not Found
일정 삭제	DELETE	/api/schedules/{scheduleId}	Path Variable	scheduleId: 1	-	204 No Content / 404 Not