REST API는 데이터를 주고받는 기능보다 협업을 위한 공통 규칙을 만드는 과정에 가깝다. URL 구조, 메서드 사용 방식, 응답 형식이 일정하면 개발 속도보다 유지보수 효율이 더 크게 올라간다.
처음 API를 설계할 때는 복잡한 패턴보다 일관된 기준을 만드는 것이 중요하다. 리소스 구조, 메서드 역할, 응답 데이터 형식만 정리해도 이후 작업은 훨씬 단순해진다.
체크 1. 리소스 중심으로 URL을 설계했는가
REST API에서는 URL이 동작보다 대상을 표현하는 것이 일반적이다.
잘못된 예시:
/getUser
/createUser
/deleteUser권장 방식:
/users
/users/1
/orders
/orders/100- URL은 명사 중심으로 설계한다
- 메서드는 행동을 담당한다
- URL 규칙은 일관되게 유지한다
API 수가 많아질수록 이런 기준 차이는 유지보수 비용에 직접 연결된다.
체크 2. HTTP 메서드를 역할에 맞게 사용했는가
HTTP 메서드는 요청 목적을 구분하는 역할을 한다.
- GET → 데이터 조회
- POST → 데이터 생성
- PUT → 전체 수정
- PATCH → 일부 수정
- DELETE → 데이터 삭제
초기 프로젝트에서는 모든 요청을 POST로 처리하는 경우가 종종 있다.
처음에는 구현 속도가 빠를 수 있지만 API가 많아지면 요청 목적을 구분하기 어려워진다.
PUT과 PATCH 차이도 자주 질문되는 항목이다.
PUT은 전체 데이터 교체에 사용한다.
PATCH는 일부 필드만 수정할 때 사용한다.
체크 3. 상태 코드는 응답 상황을 정확히 말하는가
상태 코드는 요청 결과를 빠르게 설명하는 역할을 한다.
실무에서 가장 자주 사용하는 상태 코드는 다음과 같다.
- 200 → 요청 성공
- 201 → 생성 성공
- 400 → 잘못된 요청
- 401 → 인증 실패
- 404 → 데이터 없음
- 500 → 서버 내부 오류
상태 코드가 명확하지 않으면 디버깅 시간도 길어진다.
체크 4. 요청과 응답 데이터 구조를 먼저 확인했는가
API 구현 전에 요청과 응답 구조를 먼저 정리하는 편이 좋다.
요청 예시:
{
"name":"Kim",
"email":"[email protected]"
}응답 예시:
{
"id":1,
"name":"Kim",
"email":"[email protected]"
}에러 응답 형식도 함께 통일하는 것이 좋다.
응답 구조가 계속 변경되면 협업 과정에서 혼란이 발생하기 쉽다.
체크 5. Postman으로 API 요청부터 응답까지 확인했는가
API 작성은 구현 이후 검증 단계가 중요하다.
테스트 과정에서는 실제 흐름을 확인해야 한다.
- API 요청 생성
- 환경 변수 등록
- 토큰 발급
- 응답 결과 확인
- 반복 테스트 실행
실무에서는 로그인 API는 정상 동작하지만 사용자 조회 API에서 401 Unauthorized가 발생하는 경우가 자주 있다.
대부분 토큰 전달 누락이나 인증 헤더 설정 문제로 이어진다.
API 품질은 복잡한 구조보다 일관성에서 나온다.
URL 규칙, 메서드 역할, 응답 구조를 처음부터 일정하게 유지하면 개발과 유지보수가 훨씬 쉬워진다.
