해당 시리즈는 【한글자막】 소프트웨어 아키텍처 및 대규모 시스템 설계 강의를 보고 정리한 내용입니다.

API 설계 개요

API란?

• 시스템을 블랙 박스라고 했을 때, 동작 이외에도 인터페이스를 만들게 됨
  • 클라이언트나 다른 엔지니어와 협의를 통해 만든 인터페이스를 통해 호출됨
  • 이 인터페이스를 Application Programming Interface라고 함

API 구별

• 개방형 API
  • 일반 대중에게 공개된 API
  • 회원 가입을 통해 API 접근 권한이나 사용자 파악을 하게 됨
• Private API
  • 사내에서 접근하고 활용하는 API
  • 계약된 대상에게만 공개되는 차이가 있음
• 파트너 API

잘 정의된 API

• 잘 정의된 API는 클라이언트가 우리 어플리케이션을 잘 몰라도 쉽게 활용할 수 있게 함
• API를 미리 잘 정의해두면 클라이언트는 모든 기능 구현을 기다리지 않아도 됨
• 잘 정의하면 시스템의 내부와 아키텍처를 쉽게 설계할 수 있음
  • API라는 엔드포인트를 미리 파악해두고 설계하기 때문

Best Practices and Patterns

1. Complete Encapsulation
   • 내부 설계와 구현으로부터 완전히 구별된 채 설계하고 구현한다
   • 시스템을 사용하려는 개발자와 API가 관계 없도록 설계한다
     • 사용자가 지나치게 비즈니스 로직이나 구현 방식에 대해 알게 될 경우 API이 상실됨
     • 사용자의 계약과 별개로 내부적으로 수정할 수 있도록 해야함
2. Easy to Use
   • 사용하기 쉽고, 이해하기 쉽고, 우연히 또는 의도적으로 오용할 수 없어야 한다
     • 데이터를 얻거나 작업하는 방법을 하나만 만든다
     • 작업 및 자원에 대해 구체적인 이름 부여한다
     • 사용자에게 필요한 정보만 공개한다
     • 모든 API에 있어서 모든 항목을 일정하게 유지한다
3. Keeping the Operations Idempotent
   • 작업이 최대한 멱등성을 지니도록 노력해야 한다
4. API Pagination
   • 페이징 기능이 없다면 큰 결과값을 가져다 주기엔 시스템 다운이 발생할 수 있음
   • 오프셋을 통해 적당한 세그먼트 내에서 값을 얻을 수 있도록 해야 함
5. Asynchronous Operations
   • 작업을 오래 기다려야 하는 큰 작업은 비동기 동작을 통해 작동할 수 있도록 해야 함
6. Versioning
   • API의 변경이 없으면 제일이지만 모든 미래를 예측할 수 없으므로 변경에 대해 기록해야 함
   • 버저닝을 통해 클라이언트와 소통하는 과정을 이뤄내야 한다

RPC

RPC란

• 원격 서버의 서브 루틴을 실행하는 클라이언트의 기능
  • Interface Description Language, 서버 스텁, 클라이언트 스텁으로 구성
• 일반 메서드 호출과 같이 사용되는데 이를 위치 투명성이라고 함
• RPC 프레임 워크는 다양한 프로그래밍 언어를 사용해도 해당 RPC를 구현한 언어를 통해 데이터를 주고 받을 수 있음
  • 데이터를 담는 각 클래스는 서버와 클라이언트에 구현되는데 이를 DTO라고 함
  • 통신 시 클라이언트와 서버는 이를 직렬화 또는 마샬링을 통해 데이터를 사용할 수 있게 가공함

RPC 장점

• 객체 메소드를 통해 손쉽게 통신 가능
• 클라이언트와 서버 간에 통신하는 과정은 개발자에 의해 추상화됨
• 서버와의 통신 실패가 단순하게 오류 또는 에러로 설명됨

RPC 단점

• 원격 메소드에 대해 느리고, 신뢰성이 낮음
  • 병목 현상이 발생할 수 있음 ⇒ 막히지 않도록 개발자가 고려해야 함
  • 시스템 서버로 네트워크와 통신하기 때문에 신뢰성이 낮음
• 실패했는지, 수신 자체를 하지 못했는지 전송하는 측에서 알 수 있는 방법이 없음

RPC가 필요할 때

• 2개의 백엔드 시스템이 통신하는 경우
• 다른 회사에 제공하는 API나 웹 서비스
• 네트워크 통신의 추상화를 원하고, 서버 시스템의 동작에만 집중하려면 좋음
• HTTP 쿠키와 같은 이점을 바라기 힘듦
• 데이터나 리소스의 비중이 적음

REST API

• 표준이나 프로토콜이 아닌 아키텍처 스타일
• 확장성, 고가용성, 기능의 품질 속성을 가진 설계를 하기 좋음
• 사용자에게 추상화 되는 것이 리소스라는 면에서 RPC와 다름
• 사용자가 몇 가지의 메소드만을 통해 자원을 이용하는 것을 허락함

RPC vs REST API

• REST API는 동적인 성질을 가짐
  • RPC는 사용자가 할 수 있는 행동이 인터페이스 단계에서 정의됨
  • REST API는 HATEOAS를 통해 더 동적으로 행동할 수 있음 ⇒ 사용자에게 응답 시 하이퍼링크등을 포함하는 방법 등
    

REST API가 고가용성을 가지는 이유

• stateless한 상태를 유지함
  • 여러 인스턴스를 써도 사용자는 신경쓰지 않고 서비스 이용 가능
• 캐시 가능성
  • 멱등성을 가지는 인터페이스에 대해 캐싱 가능

리소스 이름 짓기

• 리소스의 이름과 주소는 URI를 활용함
• 각 계층 구조는 /로 표현하고, 하위 개념을 가짐
• 비슷한 리소스 목록을 가질 수 있음
• 다양한 리소스 상태 표현 가능

올바른 이름 짓기

• 명사로만 리소스 이름 짓기
• 컬렉션 리소스와 단일 리소스 분리하기
• 명확하고 의미 있는 이름 짓기
• 리소스 식별자 사용하기

메소드와 작업

• REST API는 메소드의 개수를 제한함
  • Create, Update, Delete, Getting
• 표준 메소드가 매핑되어 있음
  • POST, PUT, DELETE, GET
• 표준 메소드는 몇몇 특징을 가짐
  • GET - 적용해도 리소스가 변하지 않음
  • GET, PUT, DELETE - 멱등성을 가짐
  • GET - 디폴트로 캐싱이 가능
  • POST - 클라이언트에게 보내는 일부 응답을 다른 메소드 형태로 캐싱 가능
• POST나 PUT 메소드는 JSON이나 XML 형태로 데이터를 보낼 수 있음