REST API 설계 원칙 심화
좋은 API 설계는 개발자 경험(DX, Developer Experience)을 높이고 유지보수를 쉽게 합니다. 정보처리기사 시험에서는 OpenAPI 3.0 스펙, API 버전 관리 전략, HATEOAS, GraphQL이 핵심 출제 범위입니다.
OpenAPI 3.0(구 Swagger)
REST API를 YAML/JSON으로 기술하는 표준 스펙입니다.
- 핵심 구성: info(메타데이터), paths(엔드포인트), components(재사용 스키마), servers, security
- $ref: 스키마 참조로 중복 제거
- 도구: Swagger UI(문서화), Swagger Codegen(클라이언트/서버 코드 생성), Prism(Mock 서버)
- AsyncAPI: OpenAPI의 이벤트 드리븐 API 버전. Kafka, WebSocket 메시지 명세
API 버전 관리 전략
- URL 경로 버전: /v1/users, /v2/users. 가장 명확하고 캐싱 친화적
- 쿼리 파라미터: /users?version=1. 선택적 버전 지정
- 헤더 버전: Accept: application/vnd.api+json;version=1. REST 원칙에 가깝지만 테스트 어려움
- 시맨틱 버저닝(SemVer): MAJOR.MINOR.PATCH. 하위 호환 변경은 MINOR, 비호환은 MAJOR
- Sunset 헤더: 구버전 폐기 일정 공지
HATEOAS(Hypermedia as the Engine of Application State)
REST의 최상위 제약 조건으로 응답에 관련 액션 링크를 포함합니다.
- 개념: 클라이언트가 API 구조를 사전에 알지 않아도 응답의 링크를 따라 탐색 가능
- HAL(Hypertext Application Language): _links, _embedded 속성으로 HATEOAS 구현
- JSON:API: HATEOAS를 포함한 표준화된 JSON API 형식
GraphQL vs REST
- GraphQL 장점: 단일 엔드포인트, 필요한 필드만 요청(Over-fetching 해결), 중첩 쿼리로 여러 요청 통합(Under-fetching 해결)
- GraphQL 단점: 캐싱 복잡, N+1 문제(DataLoader로 해결), 파일 업로드 복잡
- gRPC: Protocol Buffers 이진 직렬화. 높은 성능. 마이크로서비스 내부 통신에 적합. 스트리밍 지원
정보처리기사 기출 핵심 정리
- OpenAPI 3.0 = REST API 표준 명세(YAML/JSON)
- API 버전: URL 경로(/v1/) 가장 보편적
- HATEOAS = 응답에 관련 액션 링크 포함(REST 최상위 제약)
- GraphQL = 단일 엔드포인트, 필요한 필드만 요청
- gRPC = Protocol Buffers, 고성능 내부 서비스 통신