사용자 경험 중심의 API를 설계하기 위한 원칙과 프로세스에 관한 책

• 웹 API 설계 요소
  • 기반이 되는 비즈니스를 잘 이해하고 반영되어야 한다
  • 맞춤형 기능보다 확장 가능하고 비용 효율적인 방식으로 시장 요구 사항을 충족해야 한다
  • 개발자 경험을 무시하지 않고 설계되어야 한다
• 기본적인 웹 소프트웨어 설계 원칙
  • 모듈화 구성: 소프트웨어 프로그램에서 하나의 속성을 갖는 가장 작은 단위
  • 캡슐화: 구현 상세에 대한 이해 없이 API 사용법을 이해해서 원하는 결과를 얻을 수 있어야 한다
  • 높은 응집도와 낮은 응결도를 가져야 한다
• 리소스 기반 API 설계
  • 리소스는 데이터 모델과 동일하지 않다!!
  • 리소스는 객체 또는 도메인 모델과도 동일하지 않다
  • 데이터 모델은 어플리케이션 세부 정보에 최적화됨으로 시간에 따라 변한다
  • 데이터 모델 설계를 메시지 설계로 전환하여 세부 정보를 노출하지 않아야 한다
  • 영구적인 것으로 여기고 설계되어야 한다
  • API 문서는 항상 최우선 사항이다
• 리소스 분류
  • 독립 관계: 서로 참조는 가능하나 단독으로 존재하며 다른 리소스에 영향을 받지 않는 관계
  • 종속 관계: 상위 리소스가 없으면 존재할 수 없는 관계
    • 자식 리소스에 대한 접근을 부모 범위로 제한하기 위해 사용
  • 연관 관계: 리소스는 독립적이나 관계를 설명하기 위해 추가 속성이 필요한 관계
• API 설계 안티패턴
  • 허술한 추상화 안티패턴: 사용자의 요구를 통합하지 못하고 세부 구현을 드러낸 API
  • 출시 버전마다 변경되는 API
  • 완벽한 설계를 위해 과도한 노력이 수반되는 API
  • 미사용되는 API
  • 여러 기능을 제공하는 거대해진 하나의 API
  • 경계를 넘는 도메인에 대해 사용 목적이 과도하게 집약된 API
  • 작은 기능의 도우미 API
• ADDR 프로세스
  • 저자가 제시하는 API 설계를 위한 프로세스
  • 단계
    • 디지털 기능 식별: 고객 요구와 기대 결과를 분석해 기능 도출
    • API 액티비티 단계 캡처: 협업 세션을 통해 이해를 일치시키고 기능을 명확히 한다
    • API 경계 식별: API 경계로 그룹화하고 API를 신규 개발할지 기존 API를 변경할 지 결정
      • 언어, 용어의 변화는 제한된 콘텍스트 구분에 유용하다
      • 명사의 의미가 변경되는 것에 유의하면 경계 구분이 더 쉽다
    • API 프로파일 모델링: 협업 세션을 통해 리소스 및 작업을 도출
      • 구성
        • API 이름과 설명
        • 범위: 공개, 비공개, 파트너용
        • 입력, 상세 출력 메시지
        • 보안: 허가된 사용자, 권한
        • 생성되는 이벤트
    • 하이 레벨 설계: API 스타일을 선택하고 설계 요소를 문서화
    • 설계 정제: API의 설계에 대한 피드백 수집 및 반영
    • API 문서화: 참조 문서 및 시작 가이드를 포함한 문서 작성
• Rest 스타일 API
  • Http 안정성 분류
    • 안전함: Get
    • 멱등성: PUT, DELETE
    • 불안전함: POST, PATCH
  • Rest: 분산 구조의 하이퍼미디어 시스템을 고려한 아키텍처
    • HTTP를 기본 프로토콜로 사용해야 하는 것을 강제하지 않는다
  • 속성
    • 클라이언트/서버 구조: 독립적으로 동작하며 요청/응답 형식으로 이루어짐
    • 무상태: 서버는 사용자의 어떤 정보도 저장하지 않는다
    • 계층 구조: 클라이언트는 서버 사이의 어떠한 인프라 계층이 존재하는지 알 수 없다
    • 캐시 가능
    • 통합 인터페이스
      • 리소스 기반 식별을 통해 독립적으로 진화하고 자기 설명적 메시지를 이용한다
      • 하이퍼 미디어 제어 링크를 통해 상호작용을 확장하고 맥락(context) 기반 응답을 해야한다
  • Rest 수준 → 높은게 좋다는 뜻은 아니다
    • level 0: 모든 요청은 단일 API 또는 엔드포인트 사용
    • level 1: 고유 URL과 상호 작용하지만 추가 매개변수가 사용됨
    • level 2: 적합한 HTTP 메서드와 응답 코드 사용
    • level 3: 하이퍼미디어 제어를 포함한 자기 설명적 메시지로 응답을 전송
  • 설계 패턴
    • 너무 세분화된 CRUD로 설계하지 말고 비즈니스 기능 중심을 작성되어야 한다
    • 확장된 API URL을 통해 상태 전환 등에 대응해야 한다
    • 싱글톤 리소스: 컬렉션 외부에 존재하는 개인을 표현하는 단일 형태 리소스
      • 이를 통해 URL 표현력을 높이고 보안 강화가 가능
      • ex) GET /me
• RPC 스타일 API → ex) GRPC
  • RPC: 로컬에서 실행되는것 처럼 네트워크를 통해 코드 단위인 프로시져를 실행하는 방식
  • 프로시저 호출을 마샬링하는 과정이 필요하다
  • 개발 시간 및 런타임 성능이 좋다
  • 이름 변경 및 매개변수의 순서가 바뀌는 것에 취약하여 서버/클라이언트 결합이 강하다
• 쿼리 기반 스타일 API → ex) GraphQL
  • 강력한 쿼리 기능과 응답 형태를 제공하는 형식의 API
  • 깊은 조회를 이용하여 중첩된 리소스를 부모와 함께 검색이 가능하다
  • 얕은 조회는 응답에서 불필요한 데이터를 전송하지 않도록 할 수 있다
  • HTTP 콘텐츠 협상을 이용할 수 없고, 조건부 헤더를 통해 동시성 제어 및 낙관적 잠금을 사용할 수 없다
  • API 게이트웨이를 통해 권한 부여를 하는 것이 어렵다
• 비동기 스타일 API
  • 비동기 API: 변경 사항이 있을 때 API 클라이언트에게 비동기 푸시 알림을 통해 정보를 전달하는 형식의 API
  • API 폴링 방식의 단점
    • 새로운 항목 확인을 위해 기존 모든 항목을 요청해야 한다
    • 클라이언트 코드가 복잡해지고 서버에 차단당할 수 있다
  • 종류
• 이벤트/스트리밍 스타일 API → 비동기 스타일 API의 성격을 지님
• API 설계 개선
• API 테스트 및 문서화 전략

• 비즈니스 기능은 조직의 무엇을 설명하고, 디지털 기능을 어떻게 를 설명한다
• SAML: API를 기업 환경 내의 기존 SSO 솔루션에 연동하는데 사용가능한 표준
• 참고: Rest 오해와 진실