REST API와 인터페이스 명세
서로 다른 시스템이 오해 없이 통신할 계약을 어떻게 만드는가? 핵심 이론부터 사례 분석, 단계별 실습, 품질 검수, 종합 문제까지 혼자 학습할 수 있도록 구성한 전공 실습 교재입니다.
오늘의 질문과 학습목표
서로 다른 시스템이 오해 없이 통신할 계약을 어떻게 만드는가? 이 질문에 자신의 말로 답할 수 있고, 설계 결과물을 직접 만들고 검수하는 것이 오늘의 완료 기준입니다.
리소스 중심 URL을 설계한다.
HTTP 메서드와 상태 코드를 목적에 맞게 선택한다.
멱등성과 안전성을 구분한다.
요청·응답·오류 스키마를 명세한다.
인증과 인가의 경계를 설명한다.
버전·페이지네이션·호환성 정책을 설계한다.
혼자 공부하는 순서
- 용어를 암기하기 전에 사례에서 문제가 생기는 이유를 설명합니다.
- 좋은 예와 나쁜 예의 차이를 관찰 가능한 기준으로 적습니다.
- 예시를 보지 않고 종합 실습을 먼저 해결합니다.
- 모범답안과 비교한 뒤 빠진 조건을 다른 색으로 보완합니다.
교재 목차
- 학습 안내와 학습목표Page 02
- 제1장. 핵심 이론과 설계 원칙Page 04
- 제2장. 단계별 설계 실습Page 05
- 제3장. 사례 분석과 품질 검수Page 06
- 제4장. 종합 실습과 모범답안Page 07
- 핵심 용어와 최종 점검Page 08
- 자기주도 심화학습과 안내형 실습Pages 09–11
종합 실습 결과물, 자가진단 80점 이상, 핵심 질문 4개에 대한 자신의 답을 남기면 Day 4 학습을 완료한 것입니다.
REST API와 인터페이스 명세 핵심 이론
전문 용어는 복잡해 보이지만, 각 용어는 설계에서 반복되는 한 가지 문제를 해결하기 위해 존재합니다. 아래 표에서 “무엇을 뜻하는가”보다 “언제 필요한가”를 중심으로 학습하세요.
| 핵심 개념 | 설명 |
|---|---|
| Resource | API가 식별하고 조작하는 업무 대상입니다. |
| HTTP Method | 조회·생성·교체·부분 수정·삭제 의도를 나타냅니다. |
| Status Code | 요청 처리 결과를 기계와 사람에게 전달합니다. |
| Idempotency | 같은 요청을 여러 번 실행해도 최종 상태가 같은 성질입니다. |
| Schema | 요청과 응답 필드의 타입, 필수 여부, 제약을 정의합니다. |
| Authorization | 인증된 사용자가 해당 자원에 접근할 권한이 있는지 판단합니다. |
좋은 설계와 나쁜 설계의 차이
피해야 할 접근
POST /doReservation처럼 동사 URL 하나에 생성·조회·취소를 모두 넣는다.
권장 접근
POST /reservations로 생성하고 GET /reservations/{id}로 조회하며 DELETE 또는 상태 전이 API로 취소한다.
[HTTP Method] [리소스 URL] + [인증] + [요청 Schema] → [상태 코드] + [응답/오류 Schema]
단계별 설계 절차
문제 정의
사용 사례를 리소스와 상태 변화로 바꾼다.
구조 추출
URL은 명사와 계층 관계로 설계한다.
핵심 설계
메서드, 성공 상태 코드, 실패 상태 코드를 지정한다.
실패 조건
필드 타입, 필수값, 범위, 예시를 스키마로 작성한다.
정책 연결
인증·소유권·역할 기반 인가 규칙을 추가한다.
검증과 추적
재시도, 멱등성 키, 페이지네이션, 버전 정책을 검토한다.
작동하는 예시
예시를 읽을 때 확인할 것
- 입력과 시작 조건이 명확한가?
- 정상 결과뿐 아니라 실패 결과도 관찰 가능한가?
- 중복·권한·동시성·외부 장애가 필요한 수준으로 다뤄졌는가?
- 요구사항과 구현 결과를 서로 추적할 수 있는가?
사례 분석과 품질 검수
스스로 설명해 보기
- PUT과 PATCH는 어떻게 다른가?
- 401과 403은 언제 사용하는가?
- 오류 응답에 내부 스택을 노출하면 안 되는 이유는?
- API 버전을 URL에 둘 때의 장단점은?
각 질문에 2~3문장으로 답하고, 답을 뒷받침하는 사례를 하나씩 적으세요.
품질 자가진단 · 100점
| 영역 | 판단 기준 | 점수 |
|---|---|---|
| 정확성 | 개념과 기술 선택이 요구사항 및 사실에 맞는다. | 25 |
| 완전성 | 정상 흐름, 경계 조건, 실패와 복구를 함께 다룬다. | 25 |
| 일관성 | 용어, ID, 상태, 인터페이스가 산출물 사이에서 일치한다. | 20 |
| 검증 가능성 | 관찰 가능한 결과와 완료 기준을 제시한다. | 20 |
| 설명력 | 선택한 방법과 대안의 차이를 자신의 말로 설명한다. | 10 |
틀린 결과만 고치지 말고, 빠진 질문이 무엇이었는지 기록하세요. 좋은 엔지니어는 정답을 외우기보다 다음 설계에서 같은 누락을 막는 점검 기준을 만듭니다.
종합 실습과 모범답안
상품 주문 생성, 조회, 취소 API를 설계하세요. 중복 주문 방지와 타인의 주문 조회 차단 규칙을 포함하세요.
- 핵심 가정과 미결정 사항을 먼저 적습니다.
- 주요 설계 결과물을 표, 코드 또는 다이어그램으로 작성합니다.
- 정상 흐름과 최소 3개의 실패·경계 조건을 포함합니다.
- 자가진단표로 채점하고 개선 전후를 비교합니다.
모범답안의 핵심 방향 보기
POST /orders에는 Idempotency-Key를 받고 201을 반환합니다. GET /orders/{id}는 소유자 또는 관리자만 허용합니다. 취소는 POST /orders/{id}/cancellations처럼 업무 이벤트로 모델링할 수 있으며 이미 배송된 주문에는 409를 반환합니다.
답안 사용법
모범답안은 유일한 정답이 아닙니다. 자신의 설계가 다른 경우에는 요구사항, 비용, 복잡도, 위험 중 어떤 근거로 다른 선택을 했는지 설명할 수 있어야 합니다.
핵심 용어와 최종 점검
| 용어 | 쉽게 말하면 |
|---|---|
| Safe Method | 서버 상태 변경을 의도하지 않는 메서드 |
| Idempotent | 반복 호출의 최종 상태가 동일한 성질 |
| Pagination | 큰 목록을 여러 페이지로 나누는 방식 |
| Rate Limit | 일정 시간 내 요청량을 제한하는 정책 |
| OpenAPI | HTTP API 계약을 기술하는 표준 |
| Backward Compatibility | 기존 클라이언트를 깨뜨리지 않는 호환성 |
제출 전 8문항
- 오늘의 핵심 질문에 자신의 말로 답할 수 있는가?
- 설계의 입력, 조건, 결과가 명확한가?
- 정상 흐름뿐 아니라 실패와 복구를 포함했는가?
- 동시성, 중복 요청, 권한 문제를 검토했는가?
- 외부 시스템 장애와 타임아웃을 고려했는가?
- 선택한 방법의 단점과 대안을 설명할 수 있는가?
- 산출물 사이의 용어와 상태가 일치하는가?
- 테스트하거나 관찰할 수 있는 완료 기준이 있는가?
서로 다른 시스템이 오해 없이 통신할 계약을 어떻게 만드는가? 오늘 만든 결과물을 근거로 이 질문에 답해 보세요.
맥락으로 이해하는 핵심 용어
용어를 정의만 외우지 말고 판단 도구로 익히세요. 각 행을 정의→필요한 이유→예시 또는 주의점 순서로 읽습니다.
| 용어 | 쉬운 정의 | 왜 중요한가 | 예시 또는 주의점 |
|---|---|---|---|
| 리소스 | API가 식별하고 조작하는 업무 대상 | URL을 동사가 아닌 명사 중심으로 설계 | `/orders/{id}`처럼 일관된 경로를 사용한다. |
| HTTP 메서드 | 조회·생성·전체교체·부분수정·삭제 의도를 나타내는 동사 | 클라이언트와 서버의 공통 규칙 | GET·POST·PUT·PATCH·DELETE 의미를 혼용하지 않는다. |
| 상태 코드 | 요청 처리 결과를 기계가 읽을 수 있게 표현한 번호 | 성공·클라이언트 오류·서버 오류를 구분 | 검증 실패를 무조건 500으로 보내지 않는다. |
| 요청/응답 스키마 | 필드명·타입·필수 여부·제약을 정의한 구조 | 프론트와 백엔드의 계약 | 예시만 쓰지 말고 허용 범위와 nullable 여부를 적는다. |
| 페이지네이션 | 큰 목록을 작은 단위로 나누어 조회하는 규칙 | 응답 크기와 지연을 제어 | offset 방식과 cursor 방식의 정렬 안정성이 다르다. |
| 버전 관리 | 호환되지 않는 변경을 구분하는 정책 | 기존 클라이언트의 갑작스러운 장애를 방지 | 삭제 전에 폐기 공지와 전환 기간을 둔다. |
모바일 앱에서 주문 목록을 조회하고 주문을 생성·취소한다. 품절, 인증 만료, 중복 요청을 처리해야 한다.
안내형 실습과 문제 해결
실습 상황
모바일 앱에서 주문 목록을 조회하고 주문을 생성·취소한다. 품절, 인증 만료, 중복 요청을 처리해야 한다.
순서대로 수행하기
- 사용자 행동을 리소스와 HTTP 메서드로 바꾼다.
- 각 엔드포인트의 입력·성공 응답·오류 응답을 표로 쓴다.
- 인증, 권한, 검증, 멱등성 규칙을 명세한다.
- OpenAPI 예시와 실제 서버 응답을 계약 테스트로 비교한다.
산출물 1개, 핵심 가정 3개, 실패 사례 3개 이상을 저장하세요. 다른 학습자가 추가 질문 없이 판단 과정을 재현할 수 있어야 합니다.
결과가 다를 때 진단하기
| 관찰한 증상 | 가능한 원인 | 다음 조치 |
|---|---|---|
| 프론트가 필드를 잘못 해석 | 타입·nullable 명세 부족 | 스키마와 예시 응답 동시 제공 |
| 재시도 때 주문 중복 | POST 멱등성 정책 없음 | Idempotency-Key 지원 |
| 오류 처리가 화면마다 다름 | 오류 코드 체계 없음 | code·message·details 표준화 |
스스로 이해도 확인하기
인출 연습 — 펼치기 전에 답하기
PUT과 PATCH의 차이는?
PUT은 보통 전체 표현 교체, PATCH는 일부 필드 변경을 뜻합니다.
401과 403의 차이는?
401은 인증이 필요하거나 실패한 상태, 403은 인증됐지만 권한이 없는 상태입니다.
API 명세 완료 기준은?
독립된 개발자가 질문 없이 성공·실패 요청을 구현하고 검증할 수 있어야 합니다.
페이지를 보지 않고 오늘의 핵심 판단, 대표 실패 원인, 검증 방법을 연결해 설명하세요. 세 가지가 이어지지 않으면 놓친 용어나 진단 사례로 돌아갑니다.