기술사 학습노트 | imt-log

기술사 학습노트› 소프트웨어공학› REST·GraphQL·API 설계

SW Engineering · 한장정리

[기술사토픽] REST·GraphQL·API 설계 완벽 정리 - 한장정리

REST 원칙·HTTP 메서드·멱등성, GraphQL·gRPC와의 선택, OpenAPI 문서화·버전 전략·API 보안(OAuth2·JWT)까지 시험·실무에 연결해 정리합니다.

RESTGraphQLOpenAPIOAuth2정보관리기술사

Ⅰ. REST와 HTTP API 설계

REST(Representational State Transfer)는 자원(Resource)을 URI로 식별하고, HTTP 메서드로 의미를 부여하는 아키텍처 스타일입니다. “RESTful”은 일반적으로 자원 중심 URL, 적절한 상태 코드, 무상태(Stateless) 통신을 지향합니다.

메서드	의미	멱등성	안전(Safe)
GET	조회	O	O
POST	생성·처리(비표준 작업)	×(일반적)	×
PUT	전체 치환(또는 upsert)	O	×
PATCH	부분 수정	△(구현에 따라)	×
DELETE	삭제	O	×

멱등성(Idempotency): 동일 요청을 여러 번 보내도 서버 상태가 한 번 성공한 것과 같게 유지되는 성질. 결제·주문 API에서는 Idempotency-Key 헤더로 POST의 중복 제출을 방지합니다.

버전 관리·호환성

경로 버전(/v1/orders), 헤더 버전, 쿼리 파라미터 방식이 있으며, 공개 API는 하위 호환·폐기(Deprecation) 정책과 함께 문서화하는 것이 핵심입니다.

Ⅱ. GraphQL·gRPC와의 비교

구성도

요구사항 분석

비즈니스 요구·소비자 분석
리소스·행위 도출

↓ API 명세

API 스타일 선택

REST: 리소스 기반·HTTP 메서드
gRPC: 고성능 바이너리 Protocol Buffers
GraphQL: 클라이언트 주도 쿼리

↓ 문서화·테스트

Swagger/OpenAPI

API 명세 자동화
Mock 서버·테스트 생성

배포·버전 관리

/v1, /v2 URL 버전
하위 호환성 유지

항목	REST	GraphQL	gRPC
스타일	자원별 엔드포인트	단일 엔드포인트·쿼리 언어	IDL(Protobuf)·RPC
오버페칭	설계·필드 제어로 완화	클라이언트가 필드 선택	스트리밍·스트롱 타이핑
캐싱	HTTP 캐시 활용 용이	CDN 캐싱 설계 난이도↑	HTTP/2 기반
적합	범용·공개 API	복합 조회·모바일 BFF	내부 MSA·저지연

GraphQL은 N+1 쿼리·복잡도 제한(Depth/Rate limit)·권한 체크 위치(Resolver) 설계가 시험·실무 포인트입니다.

Ⅲ. 문서화·보안

OpenAPI(OAS)로 스키마·예시·에러 코드를 공유하고, CI에서 계약 테스트(Contract test)를 검증하는 흐름이 API-First 설계의 중심입니다.

주제	요약
OAuth2 / OIDC	위임·토큰 기반 접근. OIDC는 인증(ID 토큰) 표준을 추가.
JWT	서명·만료·클레임 검증. 비밀 정보는 페이로드에 넣지 않음.
전송·경계	HTTPS, mTLS(서비스 간), WAF, Rate limit, 입력 검증으로 SQLi·XSS 완화.

시험 포인트

“REST가 무엇인가”보다 자원 설계·상태코드·멱등성·보안·문서화가 한 문제에 묶여 나오는 경우가 많습니다.

Ⅳ. 결론

결론

API는 단순한 인터페이스가 아니라 도메인 경계와 보안 정책이 노출되는 계약입니다. REST·GraphQL·gRPC는 각각 트레이드오프가 있으며, OpenAPI + OAuth2/OIDC + 관측 가능성(로그·트레이싱)으로 운영 성숙도를 완성합니다.

“좋은 API 설계는 일관된 규칙과 명확한 실패 모델(에러 코드·재시도)에서 나온다.”

블로그: 기술사 학습노트 · imt-log.tistory.com

← 소프트웨어공학 목록