웹 API 설계

9장. 개발자 리소스

이 작품은 AI를 사용하여 번역되었습니다. 여러분의 피드백과 의견을 환영합니다: [e-mail]

아무도 사용법을 모른다면 훌륭한 API를 구축하는 것만으로는 충분하지 않습니다. API를 설계할 때 개발자가 성공하는 데 필요한 학습 자료를 제공하여 개발자를 안내하고 지원할 수 있도록 하세요.

개발자 리소스는 개발자가 API 사용 방식을 개선할 수 있도록 개발자에게 제공해야 하는 일련의 자산입니다. 시중에는 다양한 유형의 개발자 리소스가 있으며, 각 리소스는 개발 수명 주기의 여러 측면에 영향을 미칩니다. 이 장에서는 대부분의 회사가 제공하는 주요 리소스를 다룹니다. 또한 이러한 리소스를 효과적으로 활용할 수 있는 몇 가지 팁과 요령도 제공합니다.

API 문서

모든 API 또는 플랫폼에 필요한 가장 기본적인 리소스인 문서부터 시작하겠습니다.

문서는 개발자가 API에 대해 배울 수 있는 곳입니다. 간단한 README 파일을 제공하든, 개발자를 위한 전체 웹사이트를 개발하든, 개발자가 API를 가장 효과적으로 사용할 수 있는 방법을 명확하게 문서화하는 것이 중요합니다. 좋은 문서에는 개발 수명 주기의 모든 단계를 포괄하는 여러 가지 측면이 있습니다.

시작하기

시작하기 가이드는 개발자가 API에 익숙하지 않은 상태에서 초기 성공을 거둘 수 있도록 안내하는 일반적인 유형의 튜토리얼입니다. 대부분의 경우 "Hello World" 연습( )을 완료하는 형태로 제공되는데, 이는 엔지니어링 업계에서 프로그램이나 API가 "Hello World"를 출력하도록 하여 성공의 증거로 삼는 일반적인 관행에 대한 참조입니다. API가 문자 그대로 "Hello, world"를 반환할 필요는 없지만 사용자가 한 번의 API 요청을 성공적으로 수행하거나, WebSocket 연결을 열고 첫 번째 이벤트를 수신하거나, WebHook에서 POST 요청 예제를 수신한 곳으로 이동하도록 할 수 있습니다. 시작하기 튜토리얼의 임무는 개발자가 이 단계에 도달하기 위해 수행해야 하는 가장 쉽고 빠른 일련의 단계를 설명하는 것입니다( , TTHW( Time to Hello World )라고도 함).

시작하기 가이드를 API 사이트의 전면 중앙에 배치하는 것은 신규 개발자를 온보딩하는 데 중요합니다. TTHW를 간소화하고 단축하면 개발자가 API를 채택하는 데 크게 기여합니다.

간단한 사용 사례에는 하나의 시작하기 가이드가 적합하지만, 여러 사용 사례를 다루는 복잡한 API를 사용하는 경우 초기 가이드를 확장하는 추가 입문서로 보강해야 합니다. 예를 들어 "첫 번째 웹 앱 만들기", "데이터 저장 시작하기", "사용자 인증 소개" 등 각각 다른 측면에 초점을 맞춘 여러 개의 시작하기 튜토리얼을 만들 수 있습니다.

다음은 좋은 시작하기 가이드의 몇 가지 핵심 사항입니다:

사전 지식이 있다고 가정하지 마세요

문서에 있는 각 기술 용어에 대해 최대한 설명하세요. (다른 페이지로 연결되는 링크나 팝업 창을 사용하여 사용자가 특정 ...