종종 작업을 하다보면 API가 중구난방일 경우가 있습니다. 각각의 API가 같은 app에서 나왔을 거라고 믿기 힘들 정도입니다. Slack에서 자신들은 API를 어떻게 작성하는지에 대한 원칙을 작성해 놓아서 간단히 살펴보았습니다.
How We Design Our APIs at Slack - Slack Engineering
슬랙에서는 어떻게 API를 디자인 하는가? (슬랙의 API 디자인 원칙)
1. 한 가지만 잘 하면 된다.
API를 설계할 때 한 번에 너무 많은 문제를 해결하고 싶을 때가 있을것입니다. 많은 것을 하려다 보면, 복잡해지고 이해하기 어려울 것입니다. 구체적인 사용 사례를 선택하면, 단일 디자인에 집중하고, API를 단순하게 유지할 수 있습니다. 단순한 API는 이해하기 쉬울뿐만 아니라, 확장하기에도 쉽고, 안전하고 더 성능이 좋습니다. 더욱이 API에 새로운 기능을 추가하기는 쉽지만, 제거하기는 어렵습니다.
슬랙에서의 대부분의 API는 이 철학을 따라 작성 되었습니다. 그러나 어떤 경우에는 존재하는것을 부수고, API를 더 간단하게, 더 집중되도록 하였습니다.
2. 쉽고 빠르게 시작하기
개발자가 API를 이해하고 빠르게 시작하는 것이 중요합니다. 개발자가 API를 이해하는데 너무 많은 시간을 들이지 않도록 합니다. 또한 개발자가 빠르게 API를 call 할 수 있게 하기 위해서 시작하기 가이드, 자습서, 샘플코드 등 다양한 방식을 통해서 개발자에게 사용방법을 알 수 있게합니다. 그러나 빠르게 시작하는 것도 좋지만 개발자가 그 다음 과정으로 넘어갈 수 있도록 개발자가 원하는 목표에 달성할 수 있도록 하는것도 중요합니다.
초기 API 문서를 디자인 할 때 물어야하는 질문은 다음과 같습니다. 구축 중인 플랫폼에서 무엇이 가장 중요한가요?
3. 직관적인 일관성을 위한 노력
당신은 당신의 API가 항상 일관적이도록 원할 것입니다. 그것은 당신에 엔드포인드 이름, 입력 변수 그리고 응답 출력에 반영되어야 합니다. 개발자는 문서가 아닌 API만 보고도 어떤 기능을 하는지 추측해야 합니다. 그것은 이미 개발자가 알고 있던 것 처럼 작동해야 합니다. 3가지 수준의 일관성이 있습니다.
- 업계 표준과의 일관성 : 업계에서 인정하는 모범 사례를 최대한 준수
- 제품과의 일관성 : 당신의 제품의 개념을 기반으로 필드 이름을 선택. 약어, 두문자를 피하고 길게
- 다른 API 메소드들과의 일관성 : 다른 API 메소드에서 사용하는 이름이 동일해야
API 디자인 할 때 일관성을 유지하기 위해서는 API에 대한 설계지침을 만들고 기록하는 것이 좋습니다.
슬랙의 API 지침
4. 의미 있는 오류 반환
API 설계의 또 다른 원칙은 의미있는 오류를 반환하여 개발자가 문제를 더 쉽게 해결할 수 있도록 하는 것입니다. API 설계 중에 개발자들은 API에서 반환된 오류에 주의를 기울이지 않을 때가 있습니다. 불분명하게 반환된 오류는 개발자가 API 채택을 어렵게 하고 개발을 포기하게 합니다. 그러나 구현 세부정보, API 자체의 오류가 반환되도록하는 것은 좋지 않습니다.
오류 코드를 반환 하는 것 이외에도 API의 명세서가 있는 링크나 긴 형식의 에러 메세지를 반환하는 것도 좋은 방법입니다.
5. 규모(스케일)과 성능을 위한 디자인
잘못된 디자인은 성능을 제한 할 수 있습니다. 따라서 API를 디자인 하는데 다음 사항을 확인해야 합니다.
- 큰 컬렉션 페이지네이션 금지 : 종종 API는 큰 데이터베이스를 처리해야 합니다. API 호출은 결국 수천개의 항목을 반환 할 수 있습니다. 이렇게 되면 백엔드에 과부하가 걸리고, 클라이언트 속도가 느려집니다.
- 다른 컬렉션 안에 큰 컬렉션을 중첩 금지 : 이 경우 페이지네이션이 복잡해집니다.
- API 속도 제한 : API의 코드루프나 오작동 하는 경우로 인하여 애플리케이션이 중지되는것을 원치 않는다면, API를 적절하게 속도를 제한해야 합니다.
6. 큰 변경을 피하세요
제품의 새 업데이트를 출시할 때 API 변경으로 인해 클라이언트의 코드를 변경하고 싶을 때가 생깁니다. 그러나, 어떤 변경이던지 기존 앱이 변경 전과 같이 작동해야 합니다.
Slack은 어제 통했던 것이 오늘도 통해야한다는 철학이 있습니다. 그러나, 변경은 불가피합니다. 드물고 예외적인 경우에 주요 변경사항을 도입합니다. 개발자의 경험을 원활하게 하기 위해서는 얼마나 많은 통지를 하고 어느 정도 까지 할 것인지는 영향을 받는 유저 그리고 개발자가 처리해야 하는 어려움과 같은 여러 요인에 따라 달라집니다. 같은 개발자에게 자주 변경 사항을 처리하도록 요청하고 싶지는 않을 것 입니다.
항상 당신이 원할 때 변경되는 것이 아닙니다. 예상치 못하고 롤백할 수 없는 주요 변경 사항에 대응하는 방법에 대한 커뮤니케이션 계획을 세우세요
디자인 과정
1. API 사양 작성
API에 대한 사용 사례를 정의한 후에는 API 스펙(사양)을 작성해야 합니다. 이 스펙은 개발자가 사용할 API의 다양한 측면을 설명합니다. 여기에는 메소드 이름, 목적 그리고 요청, 응답, 가능한 에러들의 예제가 포함 되어야 합니다. API 스펙은 API 설계를 철저하게 생각할 수 있는 기회를 줍니다.
API 사양 예시
2. 내부 API 검토
코드를 작성하기 전에 디자인의 문제를 찾는 것이 효율적입니다. 함께 일 할 동료들과 함꼐 API를 공유하고 교차 검증하면 다양한 관점에서 API를 디자인 할 수 있는 기회를 얻을 수 있습니다. API을 어떻게 네이밍 할 지, 사용성, 보안, 성능 등에 관하여 자세히 검토하는것이 좋습니다.
3. 빠른 파트너의 피드백
개발자의 파트너에게 API 스펙 초안도 공유합니다. 그렇다면 추후 API 설계를 변경하는 등의 큰 문제 없이 더 나은 API를 빌드 할 수 있습니다.
4. 베타 테스트
새로운 API를 사용하기 전에 파트너에게 테스트를 해보도록 합니다. 이를 통해 API를 설계를 개선하고 공개 배포 전에 문제를 수정할 수 있습니다.
유연성 유지
자신의 API 작성 가이드를 설정하고 API를 검토하는 프로세스를 구축했으면 팀에서도 지침을 어느정도 이해했을 것입니다. 당신이 예측한 시나리오와 일치하지 않는 케이스를 만나는데는 긴 시간이 걸리지 않을 것 입니다. 때로는 당신의 팀에서 유지하는 지침을 따르기 위해 당신의 가이드를 수정하고 변경 하는 타협을 할 수 도 있습니다.
