[Book]일상 속 사물이 알려주는 웹 API 디자인 1부 #1

 

1. API 디자인이란 무엇인가?

API인 웹 애플리케이션 프로그래밍 인터페이스는 API로 연결된 세상의 중추에 비유할 수 있습니다. 단순히 기술적인 형태부터 제품의 형태까지 크기와 목적에 상관없이 모든 시스템은 인터페이스에 의존합니다. 

API 기반 시스템을 만들고 발전시킬 때 디자인은 가장 중요한 고려사항이 되어야 합니다. API 기반 시스템의 성공과 실패는 모두 API의 품질에 달려 있다고 해도 과언이 아닙니다. 

어떤 타입이든 API의 주된 목적은 인터페이스입니다. 인터페이스란 두 개의 시스템, 대상, 조직, 또는 그 밖의 대상들이 만나고 상호작용하는 지점을 의미합니다.

 

1.1  API 세상에는 두 종류의 API 블록이 있습니다. 

하나는 퍼블릭 API이며, 다른 하나는 프라이빗 API입니다.  얼굴 인식과 사진 저장 소프트웨어 블록은 소셜 네트워크 회사에서 만들거나 제공하지 않고 서드파티가 만들고 제공합니다. 서드파티가 제공하는 블록득은 퍼블릭 API인 것 입니다.

만든 애플리에키션이나 부서 또는 회사를 위해서만 쓰이는 것이 바로 프라이빗 API입니다. 

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

 

1.2 API 디자인이 중요한 이유

어설프게 디자인 된 인터페이스는 특정 상황에선 위험할 수도 있습니다.

개발자들은이전에 상호작용을 경험한 다른 인터페이스처럼 API도 유용하고 단순하기를 기대합니다.

API 개발자 경험이란 API를 사용하는 개발자들의 경험을 의미합니다. 이는 API 사용을 위한 등록 절차와 어떻게 API를 사용하는지에 관해 설명하는 문서화와 문제에 처했을 때 해결하는 것을 돕는 기술 지원 등을 의미합니다. 그렇지만 DX라 칭해지는 주제에서 가장 공을 들여야 하는 주제인 API 디자인을 소홀히 한다면 위에 언급한 노력은 모두 의미가 없어집니다.

 

API 디자인은 사람들이 API를 사용할 떄 진가를 발휘합니다. 사용자는 자신들과 전혀 상관없는 사소한 세부사항에 구애받지 않고 API를 사용하고 싶어 합니다. 그런 API를 만들기 위해서는 API를 디자인할 떄 실제로 무슨 일이 벌어질 것인지 세부 구현을 고민해야 합니다.

 

API 디자인 결함은 이 API를 사용하는 사용하는 소프트웨어가 들이는 시간과 노력과 비용을 증가시킵니다. 

결함 있는 API 디자인은 API 보안 측면 취약성을 야기시킬 수 도 있습니다. 의도치 않게 만감한 정보를 외부에 노출할 수도 있으며, 접근 권한이나 그룹 권한 관리를 제대호 하지 않거나 너무 많은 권한을 컨슈머에게 부여할 수 도 있습니다. API 세상에서는 종종 형편없이 디자인된 API가 시장에 공개된 이후라도 바로잡을 기회가 주어지기도 합니다. 그렇지만 세상에 공짜는 없는 법입니다. 프로바이더는 시간과 비용을 들여 그들이 만들어 낸 혼란을 바로 잡아야 하면, API 컨슈머들에게도 상당히 성가신 작업입니다.

 

1.3 API 디자인에 필요한 요소

API를 디자인하려면 인터페이스 자체에만 초점을 맞출게 아니라 인터페이스를 둘러싸는 전체 맥락을 알아야 하고 모든 사용자와 소프트웨어 자체에만 초첨을 맞출게 아니라 인터페이스를 둘러싸는 전체 맥락을 알아야 하고 모든 사용자와 소프트웨어와 관련된 사항에 공감할 수 있어야 합니다.

API 디자인에 원칙이 없다면 컨택스트에서 벗어날 가능성이 매우 큽니다. 따라서 API 디자인 할 때는 반드시 커스터머의 측면과 프로바이터 측면으로 인터페이스의 두 가지 측면을 고려해야 합니다. 

 

API의 목적은 사람들에게 이루고자 하는 바를 가급적 단순하게 이루게 해주는 데 있습니다.

반드시 모든 컨택스트를 염두에 둬야 합니다. 어떤 제약이 있는지, 어떻게 API가 누구에게 쓰일 것인지, 어떻게 API를 만들어질 것이며, 어떤 식으로 성장해 나갈 것인지 들을 말입니다. 

API의 모든 라이프사이클에 관려해야 합니다. 초기 논의부터 개발, 문서화, 지속적인 개선과 수명을 다해 제거되는 순간 사이의 모든 과정을 말입니다. 일반적으로 조직에선 많은 API를 만들게 되기 때문에, 가능한 한 일관된 느낌의 API를 구축하기 위해서라도 다른 API 디자이너들과 함께 일해서 조직에서 만들어낸 API는 모두 유사한 모양과 느낌이 들도록 해 모든 API가 이해하기 쉽고 사용하기 쉽게 만들어야 합니다.

 

 

2. 사용자를 위한 API 디자인하기

맹목적으로 데이터와 기능을노출한다고 API가 되는게 아닙니다.  사용자가 API를 사용해 이룰 수 있는 바는 사용자들에게 일단 합리적이어야 할 뿐 아니라 오해의 여지도 없어야 합니다. 우리는 서로 연관된 포괄적인 요구사항들을 정리할 수 있도록 컨슈머의 관점에 중점을 두어야 합니다. 즉, API 사용자의 관점와 API를 소비하는 컨슈머 소프트웨어의 입장으로 생각해야 합니다. 이런 관점은 API  디자인의 초석이자, API를 디자인하는 사람들에게 디자인 중 반드시 따라야 하는 원칙입니다. 이러한 점을 견지하기 위해서는 API 디자인의 관점을 이해해야 할 뿐 아니라 반대로 API 디자인에 방해되는 관점에 대해서도 이해해야 합니다. 바로 서비스를 제공하는 조직과 API를 제공하는 소프트웨어인 프로바이더 관점입니다.

API는 반드시 컨슈머의 관점에서 디자인되어야 합니다. 프로바이더 관점에서 디자인된 API는 내부 동작만을 보여주고 제공되는 목표 또한 오직 프로바이더만 이해할 수 있게 되어있습니다.  대조적으로 컨슈머 관점에서 디자인된 API는 자연스럽게 사용성이 좋아집니다. 컨슈머가 이해하기 쉽고 사용하기 쉬운 API를 만들려면 컨슈머가 API를 사용할 떄 달성할 수 있는 목표가 무엇인지 명확하게 식별하는게 중요합니다.

 

2.3 API 목표 식별 과정

소셜 네트워크 API를 생각하면 친구 추가하기 같은 목표가 나타납니다. 하지만 그렇게 단순한 설명만으로는 목표가 무엇인지 정확하게 표현하기 힘듭니다. Q. 사용자는 어떻게 친구를 추가할까요? Q. 친구를 추가하기 위해 무엇이 필요할까요?

Q. 친구가 추가되면 사용자는 무슨 결과를 반환받을까요? API를 디자인할 때 기본적으로 다음과 같은 사항들을 깊이 있고, 정확하게 이해해야 합니다.

• 누가 API를 사용하는가?
• 무엇을 할 수 있는가?
• 어떻게 하는가?
• 하기 위해서 무엇이 필요한가?
• 끝나면 무엇을 반환하는가?

2.3.1 무엇을 어떻게 하는가

API 목표 목록을 결정할 떄 자문해야 할 기본적인 질문 두 가지를 보여줍니다.

• 사용자는 무엇을 할 수 있는가?
• 사용자가 어떻게 하는가?

온라인 쇼핑 웹 사이트 또는 모바일 애플리케이션의 API를 예로 들겠습니다. 쇼핑 API에서 알아야 할 무엇을과 어떻게를 살펴보겠습니다. 사람들은 온라인에서 쇼핑할 때 무엇을 할까요? 우선 상품을 구입할 겁니다. 그렇다면 상품은 어떻게 구입할까요? 일다 상품을 쇼핑카트에 담은 뒤 결제를 합니다. 이런 식으로 상품을 구입한다는 과정은 두 단계의 목표로 나뉩니다. 상품을 카트에 담는 것과 결제를 하는 것으로 말입니다. 만약 이 두 과정을 분리하지 않았으면, 우리는 상품 구매라는 딱 하나의 목표만을 만드 뻔했습니다. 그러므로 어떻게를 생각할 떄는 반드시 과정을 분해해야 합니다. 그렇지 않으면 일부 목표를 놓치게 될 가능성이 생깁니다.

 

2.3.2 어떤 걸 입력하고 어떤 게 출력되는가

어떤 목표들은 달성하기 위해 입력(값)이 필요하거나 출력(값)이 필요한 떄도 있습니다.

입력과 출력을 결정하기 위해 각 단계를 좀 더 파고 들어가 보겠습니다.

카트에 상품을 담는 목표부터 시작하겠습니다. 사람들이 카트에 상품을 담으려면 무엇이 필요할까요? 분명 카드와 상품이 필요할 겁니다. 그럼 카트에 무언가를 담을 때마다 반환해야 할 문언가가 있을까요? 사람들이 카트에 담긴 상품을 결제할 때 필요한 건 무엇일까요? 상품이 담긴 카트가 필요할 겁니다. 그 뒤에 반환받을 주문서가 있습니다.

 

정확한 버튼과 표시들로 구성된 소프트웨어 제어판을 디자인하는 데에는 단순히 정확한 목표에 대한 시야만 필요한 것이 아닙니다. 목표를 달성하기 위해서 무엇이 필요한지와 우리에게 어떤 것들이 반환되어 돌아올지도 알아야 합니다.  API의 목표를 식별하는 것은 단순히 무엇을 할 수 있느냐로 끝나는 것이 아니라, 마찬가지로 과정 중 어떠한 데이터가 다뤄질 것인지도 함께 알아야 합니다. 그래서 질문 목록에 질문을 두 개 더해야 합니다.

• 사용자는 무엇을 할 수 있는가?
• 그들은 그걸 어떻게 하는가?
• 입력에 대한 새로운 질문: 그것을 하기 위해 무엇이 필요한가?
• 출력에 대한 새로운 질문: 그들은 무엇을 반환받는가?

2.3.3 누락된 목표가 있는가

사용자들은 어떻게 상품을 가져와서 쇼핑 카트에 담았을까요? 아마 카트에 상품을 담기 전에 이름이나 설명으로 상품을 검색했을 겁니다.  따라서 상품 검색이라는 새로운 단계를 상품 구매의 무엇을에 추가할 수 있습니다.

사용자가 상품을 검색하기 위해 무엇이 필요할까요? 아마 비정형 문자열 쿼리일 겁니다. 예를 들면 이름이나 설명 중 무엇이든 될 수 있을 겁니다. 조회 결과는 어떤 걸 반환할까요? 쿼리에 부합하는 상품 리스트업일 겁니다. 사용자는 어디서 조회 쿼리를 구할까요? 아마 직접 입력할 겁니다. 상품 목록은 어떻게 쓰일까요?사용자가 이 중 하나를 선택해 카트에 추가할 겁니다.

 

다음 단계인 카트를 결제하는 과정입니다.

이 목표는 카트를 필요로 하고 주문서를 반환합니다. 아직 카트가 어디서 오는지 조사하지 않았습니다. 그렇지만 주문서를 가지고 무엇을 할 수 있을까요? 이걸 왜 사용자에게 반환하는 걸까요? 사용자가 주문 상태를 체크할 수도 있기 때문일까요? 사용자가 자신의 주문을 관리할 필요도 있을지 모릅니다. 그러니 "사용자가 무엇을 하는가?"란 질문에 주문 관리라는 새로운 답을 추가하고 이에 대한 조사를 시작해야 합니다. 사용자는 어떻게주문을 관리할까요? 우선 주문의 상태를 확인하기 위해 지금까지 한 모든 주문을 시간 순으로 나열할 수 있어야 할 겁니다.

첫 단계는 주문 목록입니다. 주문 목록을 가져오기 위해서는 어떠한 입력이 필요할까요? 아무것도 필요 없습니다. 무엇이 반환될까요? 주문 목록일 겁니다. 이 입력들은 어디서 들어오는 걸까요? 주문 목록을 가져오기 위해서는 별다른 입력은 필요가 없스빈다. 따라서  입렧이 어디서 들어오는지 생각할 필요는 없습니다. 이제 주문 관리의 첫 번째 단계가 마무리 되었습니다.

 

두 번째 단계는 주문 상태 확인입니다. 주문의  상태를 확인하기 위해서는 어떤 입력이 필요할까요? 주문일겁니다. 그럼 무엇이 반환될까요? 주문의 상태가 반환될 겁니다. 주문은 어디서 입력되어서 오는 걸까요? 결제 완료된 카트나 주문 목록 단계에서 올 겁니다. 주문 상태를 갖고 무엇을 할 수 있을꺼요? 그저 이 데이터를 사용자들에게 제공하길 기대할 뿐 입니다. 그 외의 다른 작업이 필요하지 않습니다.

그래서 질문 목록에 질문을 두 개 더해야 합니다.

• 사용자는 무엇을 할 수 있는가?
• 그걸 어떻게 하는가?
• 그것을 하기 위해서 무엇이 필요한가?
• 사용자는 무엇을 반환 받는가?
• 누락된 목표를 식별하기 위한 새로운 질문: 입력은 어디를 통해서 들어오는가?
• 누락된 목표를 식별하기 위한 새로운 질문: 출력은 어디에서 어떻게 쓰이는가?

2.3.4 모든 사용자를 찾아냈는가?

앞에서 사용자가 상품을 검색해 키트에 추가한다고 말했습니다. 그렇치만 상품은 어디서 오는 걸까요? 분명 상품 카탈로그에서 올 겁니다. 그런데 이 상품이 카탈로그에 스스로 마술처럼 추가된 건 아닙니다. 누군가가 상품을 카탈로그에 추가했을 겁니다. 고객 입장으로 생각하면 상품을 카탈로그에 직접 추가했을 리 없습니다. 관리자가 했을 겁니다. 그렇죠?

정확한 API를 만드는데 있어 다른 타입의 사용자들을 식별하는 것은 필수적인 사항입니다. 따라서 질문을 모두 명시적으로 식별하려면 질문 목록에 또 다른 질문을 추가해야 합니다.

• 모든 사용자를 식별하고 다른 무엇을 누락시키지 않기 위한 새로운 질문 : 누가 사용자인가?
• 그들이 무엇을 할 수 있는가?
• 그들은 그걸 어덯게 하는가?
• 그들은 그것을 학 위해 무엇이  필요한가?
• 그들은 무엇을 반환받는다?
• 입력은 어디를 통해서 들어오는가?
• 출력은 어디에서 어떻게 쓰이는가?

만약 우리가 먼저 우리 API의 다른 타입의 사용자를 식별해낼 수 있다면, 우리는 목표 리스틀 좀 더 포괄적으로 만들 수 있습니다. 주의할 점은  여기서 말하는 사용자는 좀 더 넓은 의미로 쓰,였다는 점입니다. 여기서 말하는 사요자는 단순히 엔드 유저일 수 있으며, API를 소비하는 컨슈머 애플리케이션일 수도 또는 엔드 유저나 넠슈머 애플리케이션의 역할 또는 프로파일일 수도 있습니다.

 

2.3.5 API 목표 캔버스

누가 - API 를 사용하는 사용자들(도는 프로파일들)을 나열

무엇을 - API 로 사용자들이 할 수 있는 것을 나열

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

입력(원천) - 각 단계를 진행하기 위해 필요한 요소들과 그것들의 원천을 나열(누락된 누가, 무엇을, 또는 어떻게를 찾기 위함)

출력(사용처) - 각 단계의 반환과 그 쓰임새를 나열(누락된 누가, 무엇 또는 어떻게를 찾기 위함)

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

 

복잡한 컨택스트는 API 목표를 채우는 것도 어렵게 느껴질 수 있습니다. 너무 많은 사용자나 프로파일 또는 너무 많은 유즈케이스가 있는 경우가 그렇습니다. 작은 유즈케이스 집합에 집둥하시 바랍니다. 특정 목표나 지나치게 많은 단계를 포함하고 있거나 지나치게 많은 분기를 포함하고 있다면, 핵심 흐름에 집중하기 바랍니다. 그런 뒤 다른 흐름들에서 새로운 목표로 이러지는 변경 가능한 요소가 있는지 확인해봅시다. 사용자의 경우도 마찬가지 입니다. 모든 무엇들이 모두 어떤 사용자들 또는 프로파일들에 견결죄는지탐험하는 것은 어려울 수 있습니다. 그럴 떈 핵심 사용자 또는 핵심프로파일에 집중하기 바랍니다. 그런 뒤에 나머지 것들에 연결할 수 있는 변경 가능한 요소가 있는 확인해 봅니다.

API의 목표를 나열하는 것은 반복적인 과정입니다. 만들어진 리스트는 사용성,성능,봉나성과 같은 고려사항 또는 제약사항에 따라 다듬거나 수정할 필요가 있습니다.

 

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

여러분의 API 목표가 프로바이더의 관점으로 수박 겉핥기 같은 API 목표를 식별하는 것을 예방해주지는 못합니다. 이러한 함정에 빠지지 않기 위해서라도 API 목표 리스트를 만들 때, 우리가 신뢰할 수 없는 프로바이더의 관점이라는 것을 명심하고 다양한 측면으로 조사를 해야 합니다.

콘웨이의 법칙이라고 알려진 소프트웨어 디자인 업계의 금언입니다. 콘웨이 법칙은 종종 시스템 디자인이 어떻게 내부 동작에 영향을 받는지에 대한 설명으로 인용되곤 합니다. " 어떤 형태이든 시스템은 개발한 조직의 의사소통 구조를 닮아간다"

프로바이 측면에서 데이터, 코드와 비드니스 로직, 소프트웨어 아키텍처, 그리고 사람들고 구성되는 실제 조직은 회사의 의사소통 구조를 형성하므로 API 디자인에 영향을 줄 수 있습니다.

 

2.4.1 데이터가 미치는 영향

 API는 근본적으로 컨슈머와 프로바이더라는 두 개의 다른 소프트웨어 간의 데이터를 교환하는 방법을 의미합니다. 그러므로 불행한 이야기지만 일반적으로 API 디자인은 데이터 구조에 유사하게 표현되는 경향이 있습니다. 게이터의 체계라던가, 데이터와 관련된 요소들의 이름 등이 API 디자인에 영향을 미칩니다.데이터베이스 모델이 외부로 노출되는 경우는 보통 안 좋은 아이디어가 만들어 낸 결과이며 사용자의 경험을 불편하게 만듭니다. 

데이터의 체계와 이름을 그대로 API 목표와 데이터에 매핑하는 것은 이해하기도 어렵고 사용하기도 어렵게 만듭니다. API 목표 캔버스를 이용하면 일반적인 디자인 문제를 회피할 수 있자만, 여전히 디자인적 문제들은 발생합니다. 그래서 API   목표를 식별하는 동안 무엇이나, 어떻게,입력 또는 출력에서 불필요하게 데이터 모델을 사용자들에게 노출해 불편한을 유발하지 않도록 주의해야 합니다.

 

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

쇼핑 API의 구현을 살펴보면, 각각의 고객은 활성화된 주소를 하나씩 갖고 있습니다. 그렇지만 시스템 내부 주소들은 절대 삭제되지 않습니다. 대신에 주소들은 상태를 갖고 있어서 고객이 주소를 변경하면 비활성화됩니다. 비즈니스 로직에 영향을 받은 API 다지인이 프로바이더 관점에서 해결할 수 있는 목표둘은 아래와 같습니다.

- 고객의(활성화된 또는 비활성화된) 주소를 가져온다

- 고객의 주소를 추가한다

- 주소의 상태를 수정(활성 또는 비활성)한다

API의 전반적인 목표는 컨슈머가 내부적으로 시스템이 어떻게 동작하는지 정확히 모르게 하는 것입니다. 위 목표들은 내부적으로 데이터를 어떻게 취급하는지 노출하고 있습니다. 

 

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

상품을 검색하고 상품 설명이나 가격 같은 고객에게 필요한정보를 보여주기 위해 먼저 제품 검색 목표를 통해서 설명을 가져와야 하고, 그 뒤에 찾아낸 상품의 가격을 가져오는 상품 가격 가져오기 목ㅎ표를 통해 필요한 정보를 가져와야 합니다. 

따라서 필수정보인 카탈로그 설명과 카탈로그 가격 정보를 구현에서 합쳐 하나의 상품 검색 목표로 묶어 아래와 같이 제공하는 것이 더 나을 것입니다.

  2.4.4 인적 조직으로 인한 영향

 API를 제공하는 조직이 한 명 이상으로 이루어진 이상, 여러분은 인적 조직 측면에서 프로바이더 관점과 맞서게 될 겁니다.

만약 프로바이더의 관점으로 디자인되었다면, API는 인적 조직의 목표를 노출할 수 있습니다. 이런 API 목표가 가진 문제는 조직과 전혀 무관한 외부 인물에게 조직 내부의 업무 방법을 보여준다는 것입니다. 컨슈머는 주문을 준비하고 주문을 배송하는 목표를 사용하겠습니다. 컨슈머의 관점에서 보자면, 모든 것은 카틀르 결제하는 목표를 달성하면 끝나야 합니다. 컨슈머가 카트를 결제할 때, 구현이 재고 관리 부서에 주문 준비를 발생시킬 것이고, 그런 뒤에 재고 관리 부서가 다시 배송 관리 부서에 주문 배송을 발생시킬 겁니다. 이 나머지 절차들은 내부에서만 다뤄져야 합니다. 

---

수정된 API 목표 캔버스 & 질문

• 누가 사용자인가?
• 그들이 무엇을 할 수 있는가?
• 그들은 그걸 어덯게 하는가?
• 그들은 그것을 학 위해 무엇이  필요한가?
• 그들은 무엇을 반환받는다?
• 입력은 어디를 통해서 들어오는가?
• 출력은 어디에서 어떻게 쓰이는가?

 

위 내용은 영진닷컴 일상 속 사물이 알려주는 웹 API 디자인 내용을 기반으로 작성되었습니다.