1. 어떤 관점으로 API를 디자인해야하는가? 그 이유는 무엇인가요

API는 사용자들의 목표를 달성하기 위해서 존재합니다. 사용자의 목표란 사용자가 API를 사용함으로써 이루고자 하는 바이며, 목표는 합리적이어야 할 뿐 아니라 오해의 여지도 없어야 합니다. 목표 식별이야말로 API 디자인 과정에서 가장 중대한 단계라고 할 수 있습니다.

사용자는 API를 통해 달성하고자 하는 목표에만 관심이 있습니다. 예를 들어 여러분이 전자레인지를 사용할 때, 내부 회로의 작동 방식이나 역사에 대해 궁금해하지 않습니다. 우리는 그저 음식을 데우는 목표만 달성하면 그만입니다. API도 마찬가지입니다. 사용자들은 API의 비즈니스 로직이나 내부 구조, 작업 방식에 관심이 없습니다. 비즈니스 로직이나 내부 구조, 작업 방식의 노출은 인터페이스를 복잡하게 만들고 이해하고 사용하기 어렵게 만들 뿐입니다.

복잡성 또는 단순성은 API를 디자인할 때 무엇에 집중했느냐에 따라 달라집니다. 관심사를 벗어나는 내용은 감추고 사용자가 할 수 있는 일에 집중하면 인터페이스는 단순해집니다.

그래서 우리는 컨슈머의 관점(API 사용자이자 소비하는 컨슈머 소프트웨어)에서 API를 디자인 해야 합니다. 이러한 관점이 API 디자인의 초석이자 디자인 중에 반드시 따라야 하는 원칙입니다.

2. API의 실제 목표를 정확하게 결정하는 방법

목표를 정확하게 결정하기 위한 과정은 API 목표 캔버스를 통해 6단계로 나눌 수 있습니다.

어떻게 - 무엇을 단계별로 분해해 나열

입력 - 각 단계를 진행하기 위해 필요한 요소들과 그것들의 원천을 나열

출력 - 각 단계의 반환과 그 쓰임새를 나열

목표 - 명시적이고 간결하게 각각의 어떻게 + 입력 + 출력을 재구성

API 목표 캔버스

누가 (API 사용자) 무엇을 (API사용자들이 할 수 있는 것) 어떻게 (무엇을 단계별로) 입력 (각 단계를 진행 하기 위해 요소 나열) 출력 (각 단계의 반환과 그 쓰임새) 목표 (명시적이고 간결하게 각각의 어떻게 + 입력 + 출력을 재구성)
코드숨 멤버 공부방을 예약한다. 주말에 예약 할수있다 날짜, 계획 예약 안내 날짜, 계획을 입력해서 예약한다.

예약 시나리오

  • 누가 사용자인가요?
    • 코드숨 멤버
  • 그들은 무엇을 할 수 있나요?
    • 공부방을 예약할 수 있습니다.
  • 그들이 그걸 어떻게 한가요?
    • 원하는 날짜를 선택해서 예약을 할 수 있습니다.
  • 무엇이 필요하나요?
    • 예약 날짜와 계획이 필요합니다.
  • 그들은 무엇을 반환받나요?
    • 예약 안내를 받습니다.

3. API를 디자인할 때 피해야할 프로바이더 관점은 무엇일까요?

프로바이더 관점에서 디자인된 API는 사용자가 API를 쓸 때 알아야 할 지식이 늘어나서 이해하기 어렵고, 사용하기 어려운 API가 됩니다. 또한 내부 로직이 노출되면 프로바이더에게 위험할 수 있습니다. 따라서 프로바이더 관점에서 API를 디자인하지 않도록 해야 합니다.

그렇다면 피해야 하는 프로바이더 관점에는 어떤 것들이 있을까요?

  1. 데이터

    일반적으로 API 디자인은 데이터의 구조에 유사하게 표현되는 경향이 있습니다. 데이터의 체계라던가, 데이터와 관련된 요소들의 이름 등이 API 디자인에 영향을 미칩니다. 여러분의 API 목표 리스트와 데이터가 여러분의 데이터베이스의 구조나 이름 등으로 밀접하게 연관된 경우, API를 프로바이더의 관점으로 디자인하고 있을 가능성이 있습니다. 이런 경우, 즉시 API의 사용자들이 정말 이런 세부 요소에 접근할 필요가 있는지 재확인 해야합니다. 데이터 베이스 모델이 외부로 노출되는 경우는 보통 안 좋은 아이디어가 만들어 낸 결과이며 사용자 경험을 불편하게 만듭니다.

    예를 들어 코드숨 공부방을 이용하고 회고를 등록할 수 있는 API를 설계하고 있다고 가정해 보겠습니다. 데이터는 예약이라는 데이터와 회고라는 데이터로 관리되고 있고, 해당하는 예약에 회고를 등록해야 하기 때문에, 데이터 관점에서 API를 만든다면 예약을 등록하고, 회고를 따로 등록해야 합니다. 이렇게 되면 사용자는 예약과 회고를 둘 다 따로 저장해야 하고, 각각 관리해야 한다는 사실을 알고 있어야 API를 사용할 수 있어서 알아야 할 지식이 늘어나서 이해하기 어렵고 사용하기 어렵게 만듭니다.

  2. 코드와 비즈니스 로직

    API의 전반적인 목표는 컨슈머가 내부적으로 시스템이 어떻게 동작하는지 정확히 모르게 하는 것입니다. 비즈니스 로직이 노출되는 경우 내부적으로 데이터를 어떻게 취급하는지 컨슈머들이 알게 됩니다. 내부의 비즈니스 로직을 노출하는 것은 API의 컨슈머가 이해하기도 어렵고 사용하기도 어렵게 만들뿐더러 프로바이더에게도 위험합니다. API의 목표를 식별할 때, 우연이라도 내부 비즈니스 로직이 노출되는 경우가 있는지 항상 확인해야 합니다.

    코드숨의 공부방 예약 수정 로직으로 예를 들어보겠습니다.

    • 회원의 예약을 가져온다.
    • 예약의 방문일자와 계획을 변경한다.
    • 회원의 수정된 예약을 저장한다.

    이를 통해 회원은 코드숨이 본인의 예약 데이터를 어떻게 취급하는지 알게 됩니다. 각 목표를 이해할 수는 있으나, 이 목표들을 어떻게 따로 사용할 수 있는지 또는 함께 쓰는지 쉽게 이해 못할 수 있습니다.

  3. 소프트웨어 아키텍처

    드러나지 않아야 하는 소프트웨어 아키텍처와 API 디자인을 매핑 시키는 것은 컨슈머가 API를 이해하기도, 사용하기도 어렵게 만듭니다. 따라서 소프트웨어 아키텍처는 항상 숨겨져야 합니다.

    예를 들어서 사용자가 코드숨 공부방을 예약한다고 가정해 보겠습니다. 예약이 가능한지 스케줄을 확인하기 위해 스케줄 일정을 조회하는 일정 API를 호출하고 나서 일정을 확인하고 예약을 등록해야 한다면, 사용자는 아키텍처 구조를 알게 됩니다. 따라서 지정된 날짜에 등록한다는 API만 있어서 이 API만 호출하고 내부적인 구조는 모르도록 만들어야 합니다.

  4. 인적 조직

    인적 조직의 목표는 컨슈머의 목표와 무관한 정보를 알려주는 것과 같습니다. 또한 숨겨야 하는 인적 조직을 API에 노출시키는 것은 API를 이해햐기 어렵고 사용하기 어렵게 만들뿐더러 전혀 관련 없는 일입니다. 그래서 API목표를 식별하는 동안에는 항상 컨슈머의 관심사에 부합한 목표인지 확인할 필요가 있습니다.

    주문 관련 작업은 ‘주문 부서’, 재고 관련 작업은 ‘재고 부서’, 배송 관련 작업은 ‘배송 부서’와 같이 주문 시스템은 여러 조직으로 구성되어 있다고 해봅시다. 만약 컨슈머에게 이러한 인적 조직이 노출된다면, 컨슈머가 직접 주문 부서에 주문을 넣고, 재고 부서에 재고 준비를 요청하고, 배송 부서에 배송을 요청하게 될 것입니다.

    컨슈머의 관점에서 보자면, 모든 것은 카트를 결제하는 목표를 달성하면 끝나야합니다. 컨슈머가 카트를 결제할 때, 구현이 재고 관리 부서에 주문 준비를 발생 시킬 것이고, 그런 뒤에 재고 관리 부서가 다시 배송 관리 부서에 주문 배송을 발생시킬 것입니다. 이 나머지 절차들은 내부에서만 다뤄져야 합니다.

결국, 모든 프로바이더 관점의 다양한 측면들로 인한 불필요한 외부 노출들은 컨슈머의 API에 대한 관심사와는 전혀 관계가 없습니다.