API 설계에 관해서...

BlackBox

프로그램은 입력에 따른 출력을 제공한다.

사용자 입장에서는 내부 구현이 어떻게 되었는지는 크게 신경쓸 필요가 없다. 

사용자는 원하는 정보나 행동이 있을 것이고, 이에 대한 응답으로 출력을 제공받을 뿐이다. 

즉, 사용자 입장에서는 정상적으로 동작을 잘하고 사용하기 쉬운 인터페이스가 중요하다.

(내부적으로 얼마나 코드가 잘 짜여져 있는지는 대부분의 사용자 입장에서는 첫번째 문제가 아니다.)

인터페이스를 어떻게 설계하는지는 매우 중요한 문제이다.

 

프로그램은 인터페이스를 사용자에게 API 형태로 제공하기도 한다.

API 를 기준으로 잘 정의된 API 가 왜 중요한지, 그리고 설계 시 어떤점을 고려해야하는지 알아보자.

잘 정의된 API 의 이점

1. 이해하기 쉽고, 사용하기 쉽다.
2. 다른 프로그램(B)과 통합을 할 경우, 프로그램(A)이 만들어질 때까지 기다리지 않아도 된다.
   • 입출력이 정의되어 있고, 프로그램(A) 내부 구현에 대한 고려를 하지 않아도 되기 때문이다.
3. Black Box 내부를 설계하고 구현하기 쉬워진다.
   • 입출력이 잘 정의되었기 때문에, 개발이 간소화되고 시간과 비용을 절약할 수 있다.

API 설계시 고려할 점

Black Box 의 설계/구현에서 구분된 상태로서, API 를 설계해야 한다.

1. 특정 일을 하는 방법은 한가지만 있어야 한다.
   • 유사한 방법이 있다면, 어떤 API 를 사용해야하는지 혼란을 줄 수 있다.
2. API 이름을 통해, 어떤 행동/정보를 하는지 예측할 수 있어야 한다.
   • 문서를 읽어보지 않아도, API 를 쉽게 사용할 수 있다.
3. API 를 사용하는 규칙이나 이름은 일관성이 있어야 한다.
   • 하나의 API 를 사용하면, 다른 API 를 기존 API 로 추론가능하므로 사용자들이 사용하기 쉽다.
4. 가능한 동일한 요청에 매번 동일한 결과를 줄 수 있어야 한다.
   • 동일한 요청에 동일한 응답을 주지 않는 은행 입출금을 생각해보자. (처리 후 잔고를 응답함) 
   • 은행에 돈을 입금하는 요청/응답에 대한 데이터가 소실될 경우, 이 상황을 처리하기 쉽지않다.
5. 사용자가 원하는 부분의 정보만 제공해야 한다.
   • 원하지 않는 데이터는 사용의 복잡성을 증가시킨다.
6. 출력되는 정보의 양 많다면, 정보의 양을 제한해야 한다. (paging)
   • 상대방의 상황에 따라, 많은 양의 데이터를 처리하지 못할 수도 있다.
      ex. 구글에 검색하면, 검색결과는 엄청나게 많지만 우리에게는 일부만 보여준다.
   • 출력되는 정보의 양을 제한하고, 오프셋을 사용한다.
     (오프셋은 데이터의 어느 지점부터 출력할지를 결정한다.)
     ex. 총 데이터가 100개 있다. 출력으로는 10개만 제공한다고 할 때,
           오프셋을 50으로 잡으면 50번째 데이터부터 10개만 제공한다.
   • 다음 정보를 받고 싶다면, 오프셋을 늘려주기만 하면 된다.
7. 출력을 생성하는데 시간이 오래걸린다면, 비동기적으로 처리해야 한다.
   • 일단 응답을 바로 해서, 사용자가 응답을 기다리지 않고 다른 작업을 할 수 있도록 해야 한다.
   • 응답은 현재의 처리상황을 알려줄 수 있도록 한다.
8. API 수정 시, 버전화를 고려한다.
   • 요구사항은 변경되는 경우가 많으며, 미래의 요구사항을 모두 예측할 수 없다.
   • 언젠가 현재 API 에 대한 호환성을 깨뜨려야하는 지점이 오게 된다. 이 때는, API 에 버전을 매겨서 처리하도록 한다.