Youngwon

API 설계, 구현, 명세

4 min read

  • REST와 RPC(gRPC)
  • OpenAPI

사례 연구: 참석자 API의 설계

  • 레거시 컨퍼런스 시스템을 API 주도 아키텍처로 마이그레이션
  • 첫 단계로 참석자 서비스를 새로 구현
    • 참석자 서비스는 생산자를 담당, 레거시 컨퍼런스 시스템, 외부 CFP 시스템은 소비자를 담당
    • 서비스간 느슨한 결합이 필요함

REST에 대한 소개

  • REST(REpresentation State Transfer)는 아키텍처적 제약의 집합
  • RESTful
    • 생산자와 소비자간 상호작용은 생산자가 리소스를 모델링하고 소비스자는 그 리소스와 상호작용 하는 형태로 정리
    • 생산자는 상태가 없음, 즉 소비스가 보낸 이전 요청을 캐싱하지 않음
    • 소비자에게 일관된 인터페이스를 제공
  • REST와 HTTP
    • 응답에는 상태코드, 메시지가 포함되어있음
  • 리처드슨 성숙도 모델

원격 프로시저 호출(RPC) API에 대한 소개

  • RPC(Remote Procedure Call)는 한 프로세스의 메서드를 호출하지만 스 메서드의 실행은 다른 프로세스에서 이루어짐
  • REST는 도메인 모델을 투영 할 수 있고 기술에 대한 추상화를 제공, RPC는 메서드를 그대로 노출해서 직접 호출하는것이 가능
  • gRPC는 RPC의 오픈소스
  • REST와 RPC의 주요 차이점은 상태관리
    • REST는 상태가 없음, RPC는 구현에 따라 상태가 있을 수 있음
    • 상태로 인해 신뢰성 및 라우팅 복잡도라는 잠재적 비용으로 고성능이라는 편의성을 얻을 수 있음

그래프QL

  • 쿼리 언어를 제공, 클라이언트는 필요한 필드만 정확하게 요청 가능
  • 여러 API에 대해 원하는 필드 지정가능, 즉 여러 API를 조합해서 사용가능

REST API 표준과 구조

  • REST는 기본적인 규칙이 있지만 구현과 설계 대부분을 개발자의 경험에 의존하게함
    • 에러전달, 페이징, 호환성 문제 등
  • 여기서는 Microsoft REST API 가이드라인 준수해서 설계
    • RFC-2119 사용

OpenAPI로 REST API 명세 작성하기

  • API가 늘어날수록 소비자와 API 형태 및 구조를 공유하는 메커니즘이 필요성이 증가함
  • OpenAPI Specification(OAS)를 정의하는 OpenAPI 이니셔티브가 생겨난 이유
  • 처음에는 Swagger가 처음 구현했지만 지금은 다양한 도구에서 활용

OpenAPI 명세의 실질적 활용

  • 코드 생성
    • OAS의 가장 유용한 기능중 하나는 API를 소비하는 클라이언트 측 코드를 생성하는 기능
    • OpenAPI Generator
  • OpenAPI 검증
  • 예제와 모의 데이터
  • 변경의 탐지

API 버저닝

gRPC

교환 방식과 API 형식의 선택

  • 트래픽이 높은 서비스

가이드라인: 교환 데이터의 모델링

다중 명세

정리

Graph View

Backlinks