API 디자인 : API 디자인의 기본과 API 디자인 테이블

해당 책을 읽으며 정리한 내용입니다 : http://www.yes24.com/Product/Goods/94462254

일상 속 사물이 알려주는 웹 API 디자인 - YES24

해당 게시물이 다룰 내용

• Rest에 뿌리를 두지만 맹목적이지는 않도록 실무에 적용할 수 있는 API 디자인 방법
• API 디자인과 OpenAPI
• 완벽한 API가 아니라 컨슈머에게 올바른 API
  • API 제공 조직의 디자인을 모르게, 사용자 관점의 디자인
• 여러 API 형식
  • REST
  • gRPC
  • GraphQL
• 일상을 소프트웨어처럼, 소프트웨어를 일상처럼
  • 설계는 산업적이며 드라이 하지만, 디자인은 예술과 비슷함(ex : 상품 디자인)
  • API 설계는 아트임

API 디자인 기초

API에는 세 가지 종류가 있음

• 원격 API
  • 웹 API
• 라이브러리 API
  • 개발자가 추가한
• 하드웨어 API
  • 시스템 제공

API의 주목적은 인터페이스

API는 두 개 이상의 시스템, 대상, 조직 등이 만나고 상호작용하는 지점

• 모바일 애플리케이션 사용자는 유저 인터페이스(화면 < 컴포넌트의 조합 )를 이용해 모바일 애플리케이션과 상호작용
• 애플리케이션은 다른 애플리케션과 프로그래밍 인터페이스를 이용해 상호작용

인터페이스는 구체적인 개념이 아닌 추상적인 개념임

API는 구현을 포함 종종 소프트웨어 전체를 의미하는 경우도 있음

• 구체적인 클래스는 추상적인 인터페이스를 임포트하여 구현함
  • Dependency Inversion Principle 
  • 인스턴스화 시 구체적인 인스턴스를 파라미터로 주입받음

웹 API

웹 API는 HTTP 프로토콜 기반으로 사용할 수 있는 원격 API다.

• API 프로바이더와 API 컨슈머
• 커뮤니케이션을 위한 네트워크 : 인터넷
• 웹 API는 프로토콜에 의존
  • 즉, 웹사이트처럼 HTTP 프로토콜에 의존

API가 흥미로운 이유

웹 API는 소프트웨어를 레고 블록처럼 쉽게 재조립할 수 있게 만들어줌

하나의 애플리케이션이 여러 관심사를 다룰 수 있음

• 구현을 아웃소싱 : 각기 다른 인프라, 다른 사양, 다른 관심사
  • 내가 구현한 다른 모듈에
  • 전문 업체의 서비스에

퍼블릭 API와  프라이빗 API

• 퍼블릭 API
  • 외부에 제공하는 서비스 / 제품
  • 이미 API가 있는데 왜 바퀴를 재발명 하나요?
  • for 컨슈머
• 프라이빗 API
  • 내부적으로 사용하는 서비스  제품
    
    • ex) 소셜 네트워크 회사의 소셜 네트워크 백엔드, 소셜 네트워크 타임라인 블록
      • 이 두친구는 오직 소셜 네트워크 회사의 내부에서만 사용됩니다.
  • 개발자는 컨슈머이면서 프로바이더가 될 수 있음

퍼블릭 / 프라이빗 여부는 API 노출방식(내부망, 인터넷)으로 결정되지 않습니다.
API가 누구에게 제공되느냐가 관건입니다.
모바일 백엔드 API는 인터넷으로 연결되어 있어도 여전히 프라이빗 API 입니다.

API 디자인이 중요한 이유

• API는 소프트웨어의 기술 인터페이스(상호작용점)에 불과하지 않습니다.
• 사용자가 기대하는 프로그래밍 인터페이스는 유용하고 단순해야 합니다.
• 다른 개발자들도 사용합니다.
  • 퍼블릭이건 / 프라이빗이건. API의 목적이 무엇이건, 회사의 조직구조가 어떻든간에 소프트웨어의 개발에 전혀 참여하지 않았던 개발자들이 API를 사용해야 합니다.
  • API는 새로운 개발자가 이해할 수 있도록 작성해야만 합니다.
  • 따라서 API 디자인은 생산성과 개발자 경험에도 영향을 미칩니다.
• API는 구현을 숨겨줍니다.
  • 사용자는 사소한 세부사항에 구애받지 않고 API를 사용하고 싶어한다
  • 사용자는 주문 후 제공받기만 하면 된다.
    • 얼마나 걸리는지 관심이 있을 수 있음
  • 사용자는 웨이터(API)와만 대화하면 됩니다. 주방장(백엔드)와 대화할 필요와 조리 방법에 대해 알 필요가 없습니다.

예시 : 레스토랑 주문과 API를 사용하는 상황

• 웨이터(소셜 네트워킹 모바일 애플리케이션 개발자)
  • 웨이터는 API 사용자에게 사진과 메세지를 주기만 하면 됨
  • 사진이 타임라인에 추가되기 전에 어떤 처리를 거치는지 관심이 없음
  • 백엔드가 어떤 기술로 개발되어 있는지 관심이 없음
  • 웨이터는 API 컨슈머이면서 프로바이더
• 주방(백엔드 개발자)
  • 프로바이더
  • 무슨일을 하는지 숨김(구현 숨김)
  • how를 숨기고 what
• 어설픈 API 디자인은 끔직한 결과로 이어집니다.
  • 사람들은 인터페이스와 문서를 바탕으로 API를 판단/평가함
  • 아무리 문서가 훌륭해도 디자인 결함을 숨길 수는 없음
  • 이해할 수 없는 안터페이스를 가진 제품은 쓰이지 않음
  • 당신/ 회사의 평판을 깎아먹음
  • API의 디자인 결함은 API를 사용하는 소프트웨어가 들이는 시간과 노력과 비용을 증가시킴

API를 적절하게 디자인 하는 방법을 배우는 법

• 기술과 API 디자인의 모든 측면을 이해해야 함
  • 모든 사용자와 스프트웨어에 관련한 사항에 공감할 수 있어야 합니다
• 커스터머의 측면과 프로바이더 측면으로 인터페이스의 두 가지 면을 고려해야 합니다.

API의 목적

• 사람들에게 이루고자 하는 바를 가급적 단순하게 이루게 해주기
• API 스타일 : RPC, SOAP, REST, gRPC, GraphQL
  • 어떤 것은 아키텍쳐적인 스타일
  • 어떤것은 쿼리 언어
• 어떤 스타일의 API, 어떤 디자인적 결단을 내리던 디자인 방법론의 포괄적인 원리에 대한 이해가 중요
  • 디자인의 원리를 이해하는 것은 API 디자인의 한 측면
• 웹 API는 HTTP 프로토콜을 사용하여 소프트웨어를 재사용 가능한 블록으로 변화시켰습니다.
  • API를 재사용 가능한 블록으로 설계해야 합니다.
  • API는 애플리케이션을 개발하는 개발자들이 여러분의 서비스를 소화할 수 있도록 해주는 인터페이스 입니다
• 퍼블릭이던 프라이빗이던 어떤 API를 만들더라도 API 디자인을 고려해야 합니다.
• 형편없이 디자인된 API는 잘 쓰이지 않거나, 잘못 쓰이거나 전혀 사용되지 않을 수 있으며, 더욱이 안전하지도 않습니다.
• 좋은 API를 디자인하기 위해서는 인터페이스 뿐만 아니라 모든 컨텍스트를 고려해야 합니다.

사용자를 위한  API를 디자인하자

• 어떤 관점으로 API를 디자인해야 하는가?
  • 컨슈머 관점(API 사용자의 관점과 API를 소비하는 컨슈머 소프트웨어)
    • 포괄적으로 요구사항을 정리할 수 있도록 해야 함
  • 프로바이더 관점은 지양(서비스 제공조직과 API 제공 소프트웨어)
• 사용자 인터페이스를 디자인하듯 API를 디자인하자
  
  • API는 사용자의 목표를 달성하기 위해 존재
    • 소셜 네트워크 API
      • 사진 공유
      • 친구 추가
      • 친구 리스트 표시
  • 목표 식별이야말로 API 디자인 과정에서 가장 중대한 단계
  • 사용자에게 합리적이어야 할 뿐 아니라 오해의 여지도 없어야 함
• 사용자가 얻을 결과에만 집중하자. HOW에 집중하면 안된다.

HOW에 집중하면 인터페이스가 복잡해진다

• 이해하기 쉽고 사용하기 쉬우며 사용자가 할 수 있는 일을 표현하는 인터페이스
• 내부 동작 원리를 설명할 필요가 없음

API를 소프트웨어의 제어판처럼 바라보기

음식을 데운다 vs 시간, 강도동안 마그네트론을 견다

어느 쪽이 사용자가 원하는 것인가요?

컨슈머 관점에서 단순한  API

개발자가 사용할 API : duration동안 power 강도로 데우기

내부 동작을 숨긴다

이해하기 쉽고 사용하기 쉬우며 사용자가 할 수 있는 일을 표현하는 인터페이스를 만든다

• ex) how 변경이 필요할 경우 알고리즘을 콜백으로 추상화, 익명 객체로 추상화

---

API 목표 식별하기

이번 단원에서 가장 중요한 내용

사용자들이 API를 사용해 달성할 수 있는게 무엇인지 결정하는 것에서 시작

사용자들의 요구사항을 수집하고 명확히 파악하여, 목표를 조금이라도 효율적으로 정확하게 달성

API 목표 캔버스

• 누가 - API를 사용하는 사용자(또는 프로파일)을 나용
• 무엇을 - API로 사용자들이 할 수 있는 것을 나열
• 어떻게 - 무엇을 단계별로 분해해 나열
• 입력(원천) - 각 단계를 진행하기 위해 필요한 요소들과 그것들의 원천을 나열(누락된 누가, 무엇을, 어떻게 찾기)
• 출력(사용처) - 각 단계의 반환과 그 쓰임새를 나열 (누락된 누가, 무엇 또는 어떻게를 찾기 위함)
• 목표 - 명시적이고 간결하게 각각의 어떻게 + 입력 + 출력을 재구성

누락된 어떻게 찾기

누락된 무엇을 찾기

누락된 주체 찾기

API의 다른 타입 사용자를 식별하기

• 엔드 유저
• 컨슈머 애플리케이션
• 역할 또는 프로파일

여전히 입출력을 조사해서 모든 사용자를 찾을 수 있습니다.

어느 정도 정리된 캔버스

• 잘 정제된 데이터와 잘 정제된 에러는 추후 논의
• API 목표 캔버스는 조감도에 가까움
• 한 번에 모든 유즈케이스를 다루려고 노력해선 안됨
  • 대신 작은 유즈케이스 집합에 집중함
  • 핵심을 해결하고 나머지 부수적임
• API의 목표를 나열하는 것은 반복적인 과정, 한 단계씩 수행해야 함
  • 한 번에 모든 것을 해결하려 하지 말라
  • 사용성, 성능, 보안성과 같은 고려사항과 제약사항에 따라 다듬고 수정

API 디자인에서 피해야 할 프로바이더 관점

콘웨이의 법칙은 종종 시스템 디자인이 어떻게 내부 동작에 영향을 받는지에 대한 설명으로 인용됩니다.

(어떤 형태이든) 시스템은 개발한 조직의 의사소통 구조를 닮아간다

• 데이터, 코드와 비즈니스로직, 소프트웨어 아키텍처, 사람(인적 조직)은 회사의 의사소통 구조를 형성함
  • 소프트웨어 구조에 영향을 줄 수 있음

데이터가 미치는 영향

API는 근본적으로 컨슈머와 프로바이더라는 두 개의 다른 소프트웨어 간 데이터를 교환하는 방법을 의미

일반적으로 API 디자인은 데이터의 구조에 유사하게 표현됨

• 데이터의 체계(Organization)
• 데이터와 관련된 요소

테이블들이 암호화된 컬럼 이름이 컨슈머에게 직접적으로 노출됨

사용하기 어려움. 사용자는 두 개의 목표를 사용해 모든 고객의 데이터를 가져와야 함

데이터 모델의 노출은 프로바이더 관점이 들어갔다는 매우 명백한 징후임

고객정보 읽기로 변경

코드와 비즈니스 로직이 주는 영향

비즈니스 로직을 구현해 데이터를 조작하는 코드 역시 API 디자인에 영향을 줄 수 있는 요소임

예를 들어 고객 주소 수정 API를 사용자에게 아래와 같이 3개로 노출하는 경우, 비즈니스 로직의 상세가 드러납니다.

내부적으로 데이터를 어떻게 취급하는지 노출하고 있습니다.

• 고객의 (활성화된 또는 비활성화된) 주소록을 가져온다
• 고객의 주소를 추가한다
• 주소의 상태를 수정(활성화 또는 비활성화)한다

사용자가 무엇을 하고 싶은가?

데이터와, 구현(html, css, js,logic, orgarnization)을 숨길 수 있는 만큼 숨긴다)

컨슈머의 비즈니스가 아니면 숨겨야 합니다.

소프트웨어 아키텍처에서 받는 영향

쇼핑 시스템을 위해 상품 정보와 상품 가격을 두 개의 다른 백엔드 시스템에서 처리하기로 정했다고 가정해 보면,

상품 정보를 각각 두개의 API로 시스템 구조를 노출함

사용자에게는 하나로 전달할 수 없을까?

드러나지 않아야 하는 소프트웨어 아키텍처와 API 디자인을 매핑하는 것은

컨슈머가 API를 이해하기도 사용하기도 어렵게 만듭니다.

소프트웨어 아키텍처는 항상 숨겨저야 합니다.

인적 조직으로 인한 영향

사용자가 주문 부서와 재고 부서, 배송 부서를 위한 API가 따로 있다는 것을 알 필요가 없습니다.

API를 재고, 배송으로 나누어 제공하지 마세요.

사용자에게 필요한 API만 노출하세요

정말 컨슈머가 이런 걸 궁금해 할까요?

• 컨슈머가 이해하고 사용하기 쉽게 해야 합니다. API는 반드시 컨슈머 관점에서 디자인 되어야 합니다.
• API를 디자인하는 도중 의도치 않게 프로바이더 관점이 내부 동작(데이터, 코드와 비즈니스 로직, 소프트웨어 아키텍처, 그리고 인적 자원)을 노출할 수 있으며, 이 경우 필연적으로 이해하기 어렵고 사용하기 어려운 API를 만들게 됩니다.
• 포괄적이고 컨슈머 지향적인 API 목표 목록은 API의 가장 강력한 기반입니다.
• 사용자들을 식별하고, 그들이 무엇을 할 수 있고, 그들이 어떻게 하는지 식별해내고, 그들이 그것을 하기위해 무엇이 필요한지, 그리고 그들이 무엇을 반환받는지 알면 포괄적인 API 목표 리스트를 만들 수 있습니다.