Haonly's Blog

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

주제

• 어떤 관점으로 API를 디자인해야 하는가?
• 사용자 인터페이스를 디자인하듯 API 디자인하는 법
• API의 실제 목표를 정확하게 결정하는 법

API를 사용하는 사람들이 원하는 것이 무엇인지의 관점.

소셜 네트워크의 API는 사진 공유, 친구 추가, 친구 리스트 표시 등이 API의 목표이며 이러한 목표들이 효과적인 API를 디자인하는데 필요한 기능적 청사진 역할을 함

그렇기 때문에 목표 식별이 중요하며 서로 연관된 포괄적인 요구사항들을 정리할 수 있도록 컨슈머의 관점에 중점을 두어야 한다.

사용자가 얻을 결과에만 집중하는 것이 중요하다. 즉, 컨슈머 관점에서 사용하기 쉽도록 개발해야 한다.

API의 목표 식별 과정

API를 디자인할 때 고려해야 하는 점

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

-> 사용자들의 요구사항을 수집하고, 그 요구사항을 깊이 파고 들어가 정확히 이해하며, 마침내 그 목표를 조금이라도 효율적이며 정확하게 달성해야 한다.

이때 누락된 목표나 사용자는 없는지 잘 확인해야 한다.

API 목표 캔버스를 사용하여 "누가", "무엇을", "어떻게", "입력", "출력" 목표"를 설정.

누가 사용자인지와 흐름들로부터 새로운 목표를 찾아내는 과정들이 중요하다.

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

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

프로바이더 관점에서 데이터의 체계와 이름을 그대로 API 목표와 데이터에 매핑하는 실수를 하기도 하는데, 이는 이해하기도 어렵고 사용하기도 어렵게 만든다.

데이터 모델과 조작에 관한 내용은 노출되면 안 된다.

내부 비즈니스 로직의 노출은 API의 컨슈머가 이해하기도 어렵게 하며 프로바이더에게도 위험하다.

숨겨야 하는 인적 조직을 API 디자인에 매핑시키지 않아야 한다.

요약

API 목표 목록은 포괄적이고 컨슈머 지향적이어야 하며 프로바이더 관점이 드어가서는 안된다.

첫 글 쓰기 전에...

API 개발이야 여러 번 해 봤지만 제대로 설계를 하고 개발한 적은 거의 없다고 본다.

그저 개발하기 급하게 개발한 못난이 API 투성이.. ㅠㅠ 

그러다가 한 반년 전에 개발한 API를 봤는데 너무나도 엉망이라 ㅋㅋㅋㅋㅋ 진짜 너무나도 거지 같아서 새로 설계하고 다시 짜렸는데 반년 전의 나와 지금의 나의 다른 점은.. 크게 없으므로 제대로 공부를 좀 해보고 개발하려고 공부하려고 한다!

책은 그냥 이 전에 개발 잘하시는 책임님이 사시던거 기억해두고 따라 샀던 책이라 어디 구석탱이에 있던 게 생각나 꺼내왔다.

고럼 화이팅 하매~~~

1부. API 디자인의 기초

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

API는 인터페이스로 시스템 간 통신을 위한 인터페이스로 작용한다.

스마트폰의 예시를 들어봤을때,

스마트폰 UI와 비교를 들었는데, 스마트폰 화면을 터치하여 모바일 애플리케이션과 사람 간의 상호작용하는 역할을 하는 UI가 애플리케이션이 다른 애플리케이션과 상호작용을 하기 위해 작용하는 프로그래밍 인터페이스인 API와 비교할 수 있다.

모바일 애플리케이션이 백엔드와 커뮤니케이션하기 위해 인터넷을 사용하는데 HTTP를 사용 -> 그래서 웹 API라는 것

예를 들어 소셜 네트워크에 사진과 글을 올리는 과정을 설명하는데,

소셜 네트워크 백엔드가 사진과 텍스트를 수신하면, 사진은 서버의 파일 시스템에 저장되고, 텍스트는 사진의 식별자와 함께 데이터베이스에 저장된다. 

하진을 저장하기 전에 직접 만들어 둔 얼굴 인식 알고리즘을 이용해 사진 속에 친구가 포함되어 있는지 확인할 수도 있다.

위 과정을 확장하면 애플리케이션 하나가 여러 독립된 애플리케이션을 다루는 상황도 상상해 볼 수 있다고 한다.

API를 통해 사진과 텍스트를 저장하고, sns 백엔드에서는 얼굴인식 API, 저장 API, 타임라인에 추가 API 등을 호출하여 작업이 이루어진다고 이해했다. 이런 과정이 레고와 같다고 한다.

API로 접근이 가능해 어디서든 실행 가능하니 동시에 여러 곳에서 사용 가능하며 이러한 점이 API의 성능과 확장성을 관리하는데 유리하다.  

API 디자인이 중요한 이유

API를 사용하는 consumer 입장에서 사용하기 쉬워야 하기 때문인 것이 내가 생각하는 첫 번째 이유인 듯하다.

외부 API를 사용하는 경우라면 누가 개발한 지 모른 채 사용하게 되는데 이때 사용에 어려움이 없어야 좋은 API라고 할 수 있기 때문이다. 

이러한 API를 사용하는 개발자의 경험을 Developer Experience라고 한다. 사용하기 유용하고 쉽도록 개발하는 것이 API 개발의 키라고 한다.

API는 구현을 숨긴다

API 내부가 어떻게 구현되는지 consumer는 알 필요가 없다.

음식점에서 음식을 주문하는 경우와 비교를 했는데, 우리가 음식점에 가서 음식을 주문할 때 요리가 어떻게 되는지는 알지 못하고 점원을 통해 음식 주문과 서빙을 받는다.

이 점이 API를 통해 상호작용하는 점과 비슷하다. API에게 요청한 결과가 구현되고 수행되는 것은 provider 애플리케이션에서 일어난다.

어설픈 API 디자인은 끔찍한 결과를 초래

형편없이 디자인된 제품들은 잘못 쓰이거나 제대로 쓰이지 않거나 아예 쓰이지 않는다. 사용자들에게만 위험한 것이 아니라 제품을 만든 조직에도 위험하다.

(내가 만든 API가 이런 상황.. ㅠㅠㅠ)

상황이 어찌 됐든 간에 API 디자인 결함은 이 API를 사용하는 소프트웨어가 들이는 시간과 노력과 비용을 증가시킨다,

그러므로 API를 적절하게 디자인하는 법을 학습하면 된다.

모든 API가 이해하기 쉽고 사용하기 쉽게 만들어져야 한다.

라는 것이 결론이며 내가 개발해왔던 API를 생각해보면 그때는 reasonable 하다고 생각했던 것들이 전혀 그렇지 않고 내가 놓치고 개발한 점들도 참 많다. 이제라도 다시 개발해 볼 생각을 한 것만으로도 기특하다고 해야 할까.. ㅎㅎ