[번역] Slack에서 API를 설계하는 방법
지금 사용할 수 있는 API 설계 지침
원본 URL : https://slack.engineering/how-we-design-our-apis-at-slack/
Slack에서 API를 설계하는 방법
Slack에서 API를 설계하는 방법
지금 사용할 수 있는 API 설계 지침
이상 5 년 전 , 우리는 개발자들에게 여유 시간에 애플리케이션을 구축하고 우리에 게시하는 쉬운 방법 제공, 플랫폼 여유를 시작합니다( 응용 프로그램 디렉토리 ) . 오늘날 수백만 명의 사용자가 작업을 Slack으로 가져오고 플랫폼에서 885,000명 이상의 활성 개발자가 구축한 앱은 Slack에서 협업을 더욱 개선하는 데 핵심입니다.
수년에 걸쳐 우리가 가장 염두에 두는 것은 훌륭한 개발자 경험을 위한 디자인입니다. 내부에서 기능 구현을 변경할 수 있지만 기존 API에 대한 동작 계약을 제거하거나 변경하는 것은 매우 어렵습니다. 그렇기 때문에 처음부터 API 디자인에 대해 신중하게 생각하는 것이 중요합니다.
API가 잘 설계되면 개발자는 API를 좋아할 것이며 API를 사용하여 가장 창의적인 혁신가가 될 수 있습니다. 그들은 막대한 투자를 하고 때로는 API의 전도사가 되기까지 합니다. 우리는 또한 개발자의 시간과 플랫폼을 구축함으로써 위험을 감수하는 리소스를 소중하게 생각합니다. 잘못된 API 디자인은 최소한의 채택과 좌절로 이어집니다. 나쁜 API는 회사의 책임이 됩니다.
Slack이 항상 API를 잘 설계했다는 의미는 아닙니다. 우리는 실수를 저질렀고 플랫폼은 확실히 더 친근한 개발자 경험을 제공할 수 있습니다. 그러나 이러한 실수를 인식하고 개선하는 방법을 식별함으로써(때로는 현재로서는 동의하지 않을 과거 선택에 대한 일관성 을 두 배로 낮추는 경우에도) 개발자 경험을 전체적으로 개선 할 수 있습니다 .
자신만의 API 스타일 가이드를 개발한다고 해서 잘못된 결정을 내리거나 오늘의 열정적인 선택이 내일의 후회가 되는 것을 완전히 막을 수는 없지만 공개적이고 정직하며 명확하게 결정을 내리는 데 도움이 됩니다. 이 게시물에서는 API 설계 원칙과 새로운 API가 지정, 검토 및 테스트되는 프로세스에 대해 설명합니다. 결국 자신의 API 프로세스로 되돌릴 수 있는 몇 가지 아이디어가 있어야 합니다.
우리의 디자인 원칙
수년에 걸쳐 우리는 API 설계를 안내하는 원칙에 정착했습니다.
1. 한 가지만 잘하면 된다
API 설계를 시작할 때 한 번에 너무 많은 문제를 해결하려고 시도하고 싶을 수 있습니다. 많은 일을 하다 보면 복잡해지고 이해하기 어려워집니다. 특정 사용 사례를 선택하여 단일 디자인에 집중하고 API를 단순하게 유지합니다. 단순 API는 이해하기 쉬울 뿐만 아니라 확장하기 쉽고 성능이 뛰어나고 안전합니다. 또한 API에 새로운 기능을 추가하기는 쉽지만 제거하기는 어렵습니다.
Slack에서 대부분의 API는 이 철학을 따랐습니다. 그러나 어떤 경우에는 기존의 복잡한 API를 더 간단하고 집중적인 API로 분해해야 했습니다.
가장 인기 있는 API 방법 중 하나인 rtm.start 는 시간이 지남에 따라 상당히 비쌌습니다. 이 메서드는 팀, 채널 및 구성원에 대한 다양한 데이터와 함께 websocket API에 연결하기 위한 URL을 반환합니다. 팀 규모가 커짐에 따라 이 페이로드는 다루기 힘들고 커져 개발자가 처리하기에는 비용이 많이 들었습니다.
소수의 개발자가 이 메서드에서 반환된 데이터를 사용했지만 대부분의 개발자는 WebSocket에만 연결하기를 원했습니다. 그 결과, 새로운 API 방식 도입 rtm.connect 는 하나의 일을 했습니다.
페이로드에 다른 데이터를 반환하지 않고 웹 소켓 API 세션 URL을 반환을 :. 이 새로운 방법은 애플리케이션 개발자와 Slack이 rtm.start 입니다.
이 특정 이야기에서 얻을 수 있는 한 가지 교훈은 의심 스러운 경우 컬렉션에서 한정된 수의 개체를 적용하거나 페이지를 매기는 것 입니다. 합리적이고 합리적인 상한선을 정의하는 것은 시기상조 최적화가 아닙니다. 유기적 성장이 그 경계가 어디에 있는지 보여주도록 하면 더 합리적인 것으로 제한하기가 훨씬 더 어렵습니다.
2. 쉽고 빠르게 시작하세요
개발자가 API를 이해하고 빠르게 시작할 수 있는 것이 중요합니다. API에 익숙하지 않은 개발자가 합리적인 시간 내에 "Hello world" 연습을 완료할 수 있도록 하고 싶습니다. 이를 평가하는 데 사용할 수 있는 메트릭 중 하나는 "첫 Hello World까지의 시간"입니다. Slack에서는 초급 개발자가 플랫폼에 대해 배우고 앱을 만들고 약 15분 이내에 첫 번째 API 호출을 보낼 수 있기를 바랍니다. 타겟 "Time to First Hello World"는 실행하는 플랫폼과 개발자 청중의 경험 수준에 따라 달라집니다.
시작하기 가이드, 자습서, 샘플 코드 및 대화형 문서는 개발자가 빠르게 시작할 수 있도록 많은 도움이 될 수 있습니다. Slack의 설명서에는 시작하기 가이드 및 자습서 외에도 개발자가 브라우저에서 모든 API 끝점을 시험해 볼 수 있는 대화형 API 테스터가 포함되어 있습니다. 우리는 증가하는 SDK 컬렉션을 사용하여 코드에 쉽게 연결할 수 있는 여러 언어로 된 코드 조각을 짜기 시작 했습니다 (참고) .
Slack API 문서의 샘플 코드
빠르게 시작할 수 있다는 것은 좋은 일이지만 개발자가 "Hello world"를 넘어서고 있습니까? 개발자 경험을 측정하려면 개발자가 달성하기를 원하는 다른 목표에도 주의를 기울여야 합니다. Slack에서는 개발자가 최소한 한 명의 다른 사용자에게 앱을 제공하거나 앱이 명령에 따라 메시지를 브로드캐스트하는 것 이상의 작업을 수행할 수 있는 상호 작용 지점에 도달하는 것이 중요하다고 생각합니다.
초기 API 문서를 디자인할 때 항상 물어야 하는 질문은 다음과 같습니다. 구축 중인 플랫폼에서 무엇이 중요한가요?
3. 직관적인 일관성을 위한 노력
API가 직관적으로 일관되기를 원합니다. 이는 엔드포인트 이름, 입력 매개변수 및 출력 응답에 반영되어야 합니다. 개발자는 설명서를 읽지 않고도 API의 일부를 추측할 수 있어야 합니다. 그것은 그들이 이미 알고 있는 것과 유사하게 작동해야 합니다. 3가지 수준의 일관성이 있습니다.
업계 표준과의 일관성: 업계에서 인정하는 모범 사례를 최대한 준수해야 합니다.
제품과의 일관성: 제품에서 이러한 개념이라고 부르는 것을 기반으로 필드 이름을 선택해야 합니다. 약어, 두문자어 및 전문 용어를 피하십시오. 장황하게 말하십시오.
다른 API 메소드와의 일관성: 다른 API 메소드에서 사용하는 이름은 서로 일치해야 합니다.
일관성을 달성하는 가장 좋은 방법 중 하나는 API 디자인에 대한 의견을 공고히 하고 기록하는 것입니다. 특히 옳고 그른 방법이 하나도 없을 때 그렇습니다. 면을 선택하고 붙입니다. Slack에서 우리는 API에 대해 따르는 일관된 관행과 패턴을 정의하는 포괄적인 API 설계 지침을 작성했습니다.
Slack의 독창적인 API 디자인 가이드라인 미리보기
4. 의미 있는 오류 반환
API 설계의 또 다른 원칙은 의미 있는 오류를 반환하여 개발자가 문제를 더 쉽게 해결할 수 있도록 하는 것입니다. API 설계 중에 너무 자주 엔지니어는 API에서 반환된 오류에 거의 주의를 기울이지 않습니다. 정확하지 않거나 불분명한 오류는 답답하고 API 채택에 부정적인 영향을 미칠 수 있습니다. 개발자는 막혀 포기할 수 있습니다. 좋은 오류는 이해하기 쉽고 모호하지 않으며 실행 가능합니다. 개발자가 문제와 해결 방법을 이해하는 데 도움이 됩니다. 구현 세부 정보, 특히 오류가 API에서 누출되어서는 안 됩니다.
오류 코드를 반환하는 것 외에도 문서 또는 API 응답의 다른 위치에 더 긴 형식의 오류를 추가하는 것이 종종 유용합니다. 여기에는 문제 해결 방법이나 추가 정보 링크를 포함하여 사람이 읽을 수 있는 오류 설명이 포함될 수 있습니다.
Slack API의 더 긴 형식의 오류 메시지
개발자를 위한 SDK 및 라이브러리도 구축하는 경우 오류 메시지 및 경고를 "삼키지" 않는 것이 중요합니다. 개발자가 HTTP 헤더 및 원시 요청 본문과 같이 힘든 디버깅 세션에서 유용할 수 있는 모든 것에 액세스할 수 있는지 확인하십시오. SDK가 오류를 해석하고 더 유용하게 만들 수 있다면 좋겠지만 개발자는 오류에 대한 원시 API 문서를 읽고 여전히 SDK 수준에서 정확하게 지적할 수 있어야 합니다. 우리는 때때로 우리 플랫폼의 유용한 오류 메시지를 개발자들에게 빼앗아 스스로 책임을 지고 있습니다.
5. 규모와 성능을 고려한 설계
잘못된 디자인은 성능을 제한할 수 있습니다. 따라서 API를 설계하는 동안 다음 몇 가지 사항을 확인해야 합니다.
큰 컬렉션을 페이지 매김: 종종 API는 큰 데이터 세트를 처리해야 합니다. API 호출은 결국 수천 개의 항목을 반환할 수 있습니다. 이렇게 하면 웹 애플리케이션 백엔드에 과부하가 걸리고 대규모 데이터 세트를 처리할 수 없는 클라이언트의 속도가 느려질 수도 있습니다. 이러한 이유로 큰 결과 집합에 페이지를 매기는 것이 중요합니다.
다른 큰 컬렉션 안에 큰 컬렉션을 중첩하지 마십시오. 이 경우 페이지 매김은 너무 복잡합니다.
API 속도 제한: 잘못된 행동을 하는 단일 개발자 또는 코드 루프가 애플리케이션을 중단시키는 것을 원하지 않습니다. 애플리케이션의 안정성과 가용성을 높이면서 인프라를 보호하려면 적절한 속도 제한을 추가해야 합니다.
Slack의 API 중 하나인 channels.list (현재는 사용 중지됨)는 채널 목록과 각 채널의 모든 구성원을 반환하는 데 사용되며 기본적으로 컬렉션을 다른 컬렉션에 중첩합니다. Slack이 탄생했을 때 우리는 각 팀이 수백 명의 사용자로 제한될 것이라고 가정했습니다. 그러나 제품이 발전하고 성장함에 따라 그 가정은 더 이상 사실이 아니었습니다. 우리는 수만 명의 사용자를 가진 팀을 만들기 시작했습니다. 그 시점에서 동일한 API 호출에서 모든 채널과 각 채널의 멤버를 반환해야 하는 이 구조는 지원하기가 너무 어려워졌습니다. 그런 다음 이를 두 개의 서로 다른 간단한 API인
simpler APIs: conversations.list and conversations.members
로 나누었습니다. 이는 API 성능을 개선하는 데 도움이 되었을 뿐만 아니라 개발자 경험을 개선하는 데도 도움이 되었습니다. 페이지 매김이 중요할 뿐만 아니라 실수의 패턴이 동일 하기 때문에 페이지 매김이라는 주제를 다시 언급합니다 . 당신에게 "충분히 좋다" 는 것은 아마도 나머지 세계에게는 충분하지 않을 것입니다 . API의 즐거움 중 하나는 다른 개발자가 API를 어떻게 사용할지 전혀 모른다는 것입니다. 그러나 특히 자신이 동일한 API의 소비자인 경우 눈이 멀 수 있는 많은 가능성을 예상하는 것은 여전히 귀하에게 달려 있습니다.
6. 변경을 중단하지 마십시오.
제품의 새 업데이트를 출시할 때 가장 마지막으로 하고 싶은 일은 API 변경으로 인해 클라이언트의 코드를 깨뜨리는 것입니다. 그래서, 획기적인 변화는 무엇입니까? 기존 앱이 변경 전과 같이 작동하지 않도록 할 수 있는 모든 변경입니다.
Slack에서 우리가 따르는 철학은 어제 통했던 것이 내일도 통해야 합니다. 즉, 변화는 불가피합니다. 드물고 예외적인 경우에 주요 변경 사항을 도입하기로 결정합니다. 개발자의 경험을 원활하게 만들기 위해 얼마나 많은 통지를 하고 어느 정도까지 할 것인지는 영향을 받는 사용자 및 작업 공간의 수, 개발자가 처리해야 하는 어려움의 정도와 같은 여러 요인에 따라 다릅니다. 동일한 개발자에게 몇 달에 한 번씩 주요 변경 사항을 처리하도록 요청하고 싶지는 않습니다.
일이 당신이 원할 때 항상 깨지는 것은 아닙니다. 예상하지 못했고 롤백할 수 없는 주요 변경 사항에 대응하는 방법에 대한 (사과적인) 커뮤니케이션 계획을 세우십시오.
디자인 과정
잘 정의된 API 설계 지침 외에도 Slack의 모든 팀이 공개 API를 구축할 수 있도록 하는 엄격한 API 설계 프로세스도 있습니다. 다음은 우리가 수행하는 단계입니다.
1. API 사양 작성
팀이 해결하려는 문제를 파악하고 API에 대한 사용 사례를 정의한 후에는 API 사양을 작성하는 것으로 시작합니다. 이 사양은 개발자가 사용할 API의 다양한 측면을 설명합니다. 여기에는 메서드 이름, 목적, 예제 요청, 응답 및 가능한 오류와 같은 정보가 포함될 수 있습니다 . 사양은 우리에게 API 설계를 철저히 생각할 수 있는 기회를 제공합니다. 그것은 또한 우리의 목표가 무엇인지, 우리의 자원이 어떻게 노출되는지에 대해 모든 사람이 일치되도록 유지하는 중심 초안 역할을 합니다.
그런 경향이 있는 팀의 경우 OpenAPI 또는 AsyncAPI와 같은 공개 형식으로 JSON 스키마 및/또는 사양을 작성하면 구현 전에 API 프로토타입을 작성하는 데 도움이 될 수도 있습니다. 개발자를 위해 스키마를 게시하면 자체 도구를 빠르게 시작하는 데 도움이 될 수 있지만 사양을 최신 상태로 유지하려는 노력은 벅찬 일입니다. 그것은 우리가 스스로를 개선할 수 있는 또 다른 영역입니다.
API 사양 예시
2. 내부 API 검토
코드 를 작성 하기 전에 디자인의 문제를 찾는 것이 훨씬 더 효율적 입니다. Slack에서 엔지니어는 API 사양을 작성한 후 #api-decisions 라는 내부 Slack 채널에서 이를 공유합니다.. 이것은 API를 구축하는 엔지니어가 개발자 관계, 엔지니어링, 제품 관리, 개발자 지원, 파트너 엔지니어링 및 보안 분야의 사람들로 구성된 교차 기능 그룹에서 제안에 대한 다양한 관점을 얻을 수 있는 기회입니다. 변경 사항에 대해 더 깊은 논의가 필요한 경우 정기적으로 예약된 API 업무 시간에 검토합니다. 이 회의에서 그룹은 "변경 사항이 다른 기존 API와 일치합니까?" 및 "API 설계 지침과 일치합니까?"와 같은 주제에 대해 토론합니다. 또한 그룹은 변경 사항의 명명, 사용성, 보안 및 성능 고려 사항에 대해 자세히 설명합니다.
3. 초기 파트너 피드백
내부 이해 관계자와 함께 API를 구현하는 데 이상적인 개발자인 파트너에게 API 사양 초안도 제공합니다. 그들의 피드백은 API가 해결해야 할 문제를 해결하고 개선이 필요한 API 측면을 이해하는 데 도움이 되는지 확인하는 데 중요합니다. 코드를 작성하기 전에 이 피드백을 구함으로써 API 설계를 빠르게 반복하고 훨씬 더 나은 API를 빌드할 수 있습니다.
4. 베타 테스트
새로운 API를 널리 사용할 수 있도록 하기 전에 선별된 파트너에게 조기 액세스를 제공합니다. 이러한 파트너는 API를 제품에 통합하고 API에 대한 자세한 피드백을 제공합니다. 이를 통해 API 설계를 더욱 개선하고 공개 릴리스 전에 식별된 문제를 수정할 수 있는 추가 기회를 얻을 수 있습니다.
유연성 유지
자신만의 API 설계 지침을 설정하고 이에 대해 예상 API를 검토하는 프로세스를 구축하는 데 어려움을 겪었다면 이제 팀에서 지침을 어느 정도 내재화했을 가능성도 있습니다.
당신이 예측한 시나리오와 일치하지 않는 케이스를 만나기까지는 그리 오래 걸리지 않을 것입니다. 때로는 자신의 엔지니어링 조직에 도움이 되거나 여전히 실망스러운 일관성을 추구하기 위해 자신의 좋은 조언에 어긋나는 타협을 할 것입니다. 그러나 때로는 완전히 새로운 종류의 API가 제공되며 지침 의 정신 에서 영감을 얻어 교차 기능 파트너의 차단을 해제할 수 있습니다. 법조서는 나중에 언제든지 쓸 수 있습니다.
마무리 메모
직관적이고 일관되며 사용하기 쉬운 API를 설계하는 것은 어렵습니다. 이 게시물에서는 Slack에서 따르는 API 디자인 원칙과 디자인 프로세스에 대해 다루었습니다. API를 구축할 때 몇 가지 핵심 사항은 다음과 같습니다. 먼저 API 디자인에 대해 생각하는 데 시간을 할애하고, 디자인 선택에 신중을 기하고, 여러 이해 관계자로부터 피드백을 수집합니다.
