[웹 API 디자인 2장] API 디자인에도 육하원칙이 있다

https://www.aladin.co.kr/shop/wproduct.aspx?ItemId=254607285

남은 1장과 2장을 마저 해치웠습니다.

서점 갔다가 홀린듯이 사버린 책 중 하나인데, 뭔가를 만들어보려면 어느 지점에서 꼭 막히더란 말이죠. 그런 상황에서 도움이 될 것 같다고 생각했습니다.

각설하고.

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

1장의 주요 내용은 API 디자인이 왜 중요한지이고, 2장에서는 그걸 어떻게 하는지의 개요를 보여줍니다.

1장에서 그지같은 디자인의 (그냥 봐서는 뭐 하는 물건인지도 알 수 없는) 범용 원격 드론 조종장치로 예시를 들고, 2장은 보다 쉬운 전자레인지로 예시를 듭니다. 예시가 중요한 건 아니고 거기에 담긴 게 중요한데... 2장 목차부터 정리하죠.

• 2.1 일상 속 사용자 인터페이스를 디자인하는 올바른 관점
  
  • 2.1.1 작업 방식에 집중하면 인터페이스가 복잡해진다
  • 2.1.2 사용자가 할 수 있는 일에 집중하면 인터페이스는 단순해진다
• 2.2 소프트웨어 인터페이스 디자인 방법
  • 2.2.1 API를 소프트웨어의 제어판처럼 바라보기
  • 2.2.2 컨슈머의 관점에 집중해 단순한 API를 만들기
• 2.3 API의 목표 식별 과정
  • 2.3.1 무엇을 어떻게 하는가
  • 2.3.2 어떤 걸 입력하고 어떤 게 출력되는가
  • 2.3.3 누락된 목표가 있는가
  • 2.3.4 모든 사용자를 찾아냈는가
  • 2.3.5 API 목표 캔버스
• 2.4 API 디자인에서 피해야 할 프로바이더 관점
  • 2.4.1 데이터가 미치는 영향
  • 2.4.2 코드와 비즈니스 로직이 주는 영향
  • 2.4.3 소프트웨어 아키텍처에서 받는 영향
  • 2.4.4 인적 조직으로 인한 영향
  • 2.4.5 API 목표 캔버스에서 프로바이더 관점 찾기

이 내용은 책의 목차를 보고 그대로 타이핑한 게 맞습니다. 그렇지만 목차만큼 내용을 되새기기에 유용한 건 없죠.

2.1 일상 속 사용자 인터페이스를 디자인하는 올바른 관점

전자레인지의 예시가 여기에서 나옵니다. 전자레인지는 작업 방식에 집중한 나머지, 이름도 전자레인지가 아니었고 (소자의 이름인 "마그네트론"), 버튼을 누르고 있는 동안 동작한다는 괴악한 방식이었습니다.

사용자가 원하는 건 그저 음식을 (무엇을) 데우는 (어떻게) 것 뿐이었는데...

2.2 소프트웨어 인터페이스 디자인 방법

마그네트론 2000 을 전자레인지로 바꾸는 과정을 API와 대응하여, API 도 똑같이 사용자 관점에서 = 사용자가 무엇을 어떻게 하고싶은지에 초점을 맞춰야 한다는 걸 설명합니다. 그러면 쓰기 편하고 단순한 게 완성되죠. 자세한 사항은 장막 밑에 숨기자구요.

2.3 API의 목표 식별 과정

사용자 관점에서 무엇이 필요한지 단계적으로 살펴보면서, 어떻게 사용자 관점에서 필요한 API 를 찾아내는지 설명합니다. 그 결과가 "API 목표 캔버스" 라는 도구로 나타납니다. 이건 육하원칙과 굉장히 비슷합니다.

• API 목표 캔버스의 6가지 칼럼
  • 누가
  • 무엇을
  • 어떻게
  • 입력 + 입력의 원천
  • 출력 + 출력의 사용처
  • 목표 = 요약
• API 목표 캔버스의 활용방법
  
  • (입력의 원천, 출력의 사용처) 로부터 빠져있던 새로운 목표를 찾아냅니다.
  • 목표 = 요약 부분을 보고, 진짜로 이게 사용자한테 필요한 건지 다시 확인해봅니다 (2.4절)

이거 보면서 생각한 게, DDD 에서 얘기하는 도메인 디자인하는 거랑 비슷하다는 생각이 들더라구요. 이 책을 보고 DDD쪽 책을 보면 좀 더 와닿지 않았을까 싶네요.

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

API에 내부 사정을 묻히지 않기 위해, 내부 사정이 될 수 있는 게 무엇인지 알아봅니다.

• 데이터 ~= DB 구조
• 코드 & 비즈니스 구조 ~= 내부 소스의 함수 목록
• 소프트웨어 아키텍처 구조 ~= 너네 마이크로서비스 분리된 거가 API 에 반영될 필요까지는 없잖아
• 인적 조직 ~= 너네 부서가 분리되어있는 걸 API 에서까지 알아야 해?

이 과정에서 명언 몇 가지가 소개되는데...

"(어떤 형태이든) 시스템은 개발한 조직의 의사소통 구조를 닮아간다"
- 조직에서는 발명을 어떻게 하는가?, 1968년 4월, 멜 콘 웨이 (Mel Conway)

여러분에게 보시다시피, 우리에게 필요했던 것은 마지막 질문 하나였습니다.
"정말 컨슈머가 이런 걸 궁금해할까?"
이 질문 하나로, 조금이라도 컨슈머 관점 (데이터, 코드와 비즈니스 로직, 소프트웨어 아키텍처 또는 인적 조직) 을 지니고 있는지 확인할 수 있습니다.
- 책 50페이지, 2.4절 마무리부분, 아노드 로렛 (Arnoud Louret)

이런 부분은 API 디자인 외에도 정말 광범위하게 적용되는 내용이 아닌가 싶습니다.