PE Notes · SW
REST API 설계
REST·GraphQL·gRPC를 자원·질의·성능으로 가르고, OpenAPI와 명명·메서드·버전을 정리한 뒤 보안·캐시·Richardson 성숙도를 올립니다.
화면마다 필요한 필드가 다른데 고정 JSON을 통째로 주면 남거나 모자랍니다. 는 자원과 HTTP로 범용 웹을 열고, 은 클라이언트가 모양을 고르며, 는 내부 호출을 바이너리로 줄입니다. 설계는 스타일 이름보다 누가 어떤 계약을 보느냐입니다.
REST, GraphQL, gRPC
REST는 URI 자원, GET·POST·PUT·DELETE, 무상태, 캐시, 계층, 균일 인터페이스입니다. 한계는 오버페칭과 언더페칭입니다. GraphQL은 단일 엔드포인트에서 필요한 필드만 묻고 스키마가 문서가 됩니다. 대가는 N+1 질의, 파일 업로드, HTTP 캐시가 어렵다는 점입니다.
gRPC는 Protobuf와 HTTP/2, 강한 타입, 양방향 스트림입니다. 브라우저 생태계는 REST가 넓고, MSA 내부 지연은 gRPC가 유리합니다. 외부 입구는 가 프로토콜을 번역합니다.
| 비교축 | REST | GraphQL | gRPC |
|---|---|---|---|
| 계약 | 자원 URI | 스키마 질의 | Protobuf |
| 전송 | HTTP/JSON | HTTP | HTTP/2 바이너리 |
| 강점 | 캐시·범용 | 필요한 만큼 | 성능·스트림 |
| 약점 | 과다/과소 조회 | N+1·캐시 | 브라우저·디버그 |
명세, 명명, 버전
는 REST를 YAML·JSON으로 적는 표준 명세입니다. info·paths·components·security로 엔드포인트와 인증을 고정하고, UI 문서와 클라이언트·서버 골격 생성에 씁니다. 코드가 먼저면 명세가 늦고, 명세가 먼저면 구현이 어긋납니다. 둘을 CI에서 맞춥니다.
자원은 복수 명사(/users/1)이지 동사 경로가 아닙니다. GET은 조회·멱등, POST는 생성, PUT은 전체 교체, PATCH는 부분, DELETE는 삭제입니다. 성공은 200·201·204, 클라이언트는 400·401·403·404·422, 서버는 500대를 구분합니다. 버전은 /v1이 가장 분명하고, Accept 헤더는 URL을 깨끗이 하되 복잡합니다. 게이트웨이가 버전별 라우팅과 점진 이전을 맡습니다.
보안, 성능, 성숙도
인증은 API 키(단순·정적), (위임), (무상태 토큰)입니다. 인가 코드는 사용자 위임, 클라이언트 자격은 서버 간입니다. 한도( 완화), HTTPS, CORS, 입력 검증을 같이 겁니다. 입력이 곧 질의면 이 열립니다.
성능은 ETag·Cache-Control, CDN·캐시, 오프셋/커서 페이징입니다. 긴 작업은 202와 폴링·웹훅·SSE입니다. 는 0 단일 URI RPC, 1 자원 분리, 2 HTTP 메서드 올바름, 3 (다음 행동 링크)입니다. 실무 REST 다수는 레벨 2입니다. 레벨 3을 말하면 클라이언트 결합을 서버가 안내한다는 뜻을 같이 적습니다.
답안은 세 스타일 표, 명명·상태 코드·버전, OAuth/JWT, Richardson 0–3을 한 장에 씁니다.