[Dev] 좋은 API란 무엇일까 - API First Design 원칙

일을 하다가 문득 '좋은 API를 개발하려면 어떤 것들을 신경써야 할까?' 하는 생각이 들었다. 생각해보면 어떻게 하면 좋은 API를 만들 수 있는지를 설명해주는 자료는 본 기억은 거의 없었다. 그래서 구글에 무작정 좋은 API란 무엇일까? 검색해보았다.

 

목차

API First Design의 세가지 원칙

1. API는 서비스의 첫 사용자 인터페이스이다.

2. API가 먼저이고, 그 다음이 구현이다.

3. API는 설명되어야 하고, 어쩌면 그 자체로 설명가능해야 한다.

생각정리

---

API First Design의 세가지 원칙

이번 글은 Medium에 개재된 Adobe Tech Blog에 있는 Three Principles of API First Design를 번역한 내용을 다뤘습니다. 클라우드 네이티브 어플리케이션을 개발할 때 가장 주요한 원칙 중 하나이고, 이러한 원칙을 실천하는건 분명 어려운 일이라고 하네요.

---

API는 서비스의 첫 사용자 인터페이스이다.

API를 사용하는 개발자도 서비스의 이용자이다. 그리고 API는 이러한 개발자를 고려하여 디자인 되어야 한다.

 

한편, API는 당신이 개발하는 프로덕트의 기능(functionality)을 밖으로 드러낸다. 따라서 프로덕트 내부에 API에 의해 다뤄지지 않는 기능이 존재한다면 이는 GUI나 CLI, 혹은 VI(Voice Interface)에 의해서도 다뤄질 수 없고, 그 기능은 효과적으로 보이지 않게 된다.

 

마지막으로, API는 사용자가 프로덕트에 접근하고 상호작용하기 위한 가장 중요한 방법이므로, API는 매우 신중하게 설계되고 관리되어야 한다. 그러니 GUI를 디자인 하는데 시간을 들이는 만큼, API를 설계하는데 시간을 투자해야 한다. API가 무엇을 노출시키고, 무엇을 하고, 어떻게 확장되는지 말이다. 

---

 

API가 먼저이고, 그 다음이 구현이다.

일단 API가 그 자체로 관심을 기울일만한 요소임을 알면, API가 그 나름의 생애(life of its own)를 반드시 가져야 함을 알 수 있다.

 

구현(Implementation)은 어플리케이션이 발전하고, 최적화하고, 리팩토링되고, 기능이 향상됨에 따라 계속해서 변화한다. 그러나 API는 자주 변경되어서는 안 된다. 대신 매우 신중하게 천천히 개발되어야(grow) 한다.

 

Your implementation will change frequently, your API should not.

 

API와 Impl의 관계는 표면적과 부피 간의 관계로 비유할 수 있다. 다시 말해, API는 표면적이고, Implementation은 부피이다. 부피가 두배로 들어날 때 표면은 25% 밖에 늘지 않는다. 

 

특히, API의 발전은 프로덕트 혹은 서비스의 성장과 유연성 향상 측면에서 생각하는 것이 중요하다. 우아한 API의 발전은 기능 측면에서 더해지는 것이고, 요구사항 측면에서 덜어내는 것이다. 다시 말해, 변화는 불가피하지만, 우아한 API 발전을 계획하는 것은 피해가 큰 변화를 최소화하는 좋은 방법이다. 예를 들어, 필수 입력값은 옵셔널해질 수 있지만, 그 반대는 허용되지 않는다. 

 

마지막으로, 비록 어렵더라도 API와 구현부를 독립적으로 취급해야 한다. 이는 API와 구현부 간 분리(Decouple)를 가능하게 해준다. API는 단지 구현부 위의 얇은 베니어(합판 만들 때 쓰이는 얇은 나무판)가 아니라 구현부와의 계약(contract)이자 명세가 된다. 

---

 

API는 설명되어야 하고, 어쩌면 그 자체로 설명가능해야 한다.

API가 잘 사용되기 위해서는 API를 만드는 데 관여하지 않았던 사람들에게도 쉽게 이해되어야 한다. 즉, 문서화가 잘 되어있어야 한다.

 

좋은 API 설명서는 API가 사용되기 위해 필수적인 요소이다. 특히나 AI나 로봇이 단기간에 프로그래밍을 대체할 수 없기 때문에, 이는 더더욱 중요하다고 할 수 있다.

 

구체적으로, 구조화된 API 설명서가 그렇지 못한 설명서보다 좋다. 즉, 리소스의 유형, 요청 메서드, 헤더, 요청 매개 변수 및 응답 형식 등에 대한 표준들을 따라 설명서를 작성하면, 사용자가 기능을 더 쉽게 탐색하고 이해할 수 있다. 또 사용자 입장에서 느낄 당혹감을 줄이기 위해서라도 표준화된 패턴들을 따라 써주는 것이 좋다.

 

무엇보다 잘 문서화된 API도 눈에 띄게 만들어주는 것이 하나 있다. 다른 API 자원을 쉽게 찾을 수 있도록 링크와 같은 하이퍼미디어 구조를 사용해 스스로 설명하는 API이다. 이를 통해 설계, 오버 구현(over implementation), 문서화에 이르기까지 좋은 API의 제작과정을 마무리 할 수 있다. 

---

 

생각정리

현재 일하고 있는 조직에 합류한 이후 처음으로 API 개발 내용을 공유드렸을 때, 서비스 Flow와 Caller 입장에서 취해야할 Action이 문서에 같이 기술되면 좋을 것 같다는 피드백을 받았었다. 이제와 이 글을 읽으며 보니 그때의 피드백은 어쩌면 이 글에서 다루는 API 설계와 문서화에 관한 내용이었던 것 같다는 생각이 든다. 한동안 API 개발을 함에 있어 다른 레이어에 비해 코드를 짜는 데 쓰이는 손은 조금 덜 바쁠지라도 문서화 하는 데 쓰이는 손은 아주 바쁘다는 생각을 했다. 결국, 우리 시스템을 호출하는 개발자는 우리 시스템을 전혀 모르는 상태이기 때문에, API 개발자들이 앞단에서 복잡한 시스템 내부의 기능들을 인터페이스로 잘 내려줘야 하지 않을까? 무튼.. 이런 고민(API 개발 쉬워보여도 결코 쉽지 않다ㅜ)들을 나만 하고 있지 않다는 것에 위로를 얻고, 또 인사이트도 얻어갈 수 있던 포스팅이었다!

 

Reference

https://blog.developer.adobe.com/three-principles-of-api-first-design-fa6666d9f694