블로그

Jul 05, 2023

API 문서의 10가지 중요한 구성 요소

API는 문서만큼 우수하므로 귀하의 API를 검색할 수 있는지 확인하세요.

API는 문서만큼 우수하므로 최고 품질의 지침과 기타 중요한 세부 정보를 통해 API를 검색할 수 있는지 확인하세요.

점점 더 많은 조직이 API의 강력한 기능을 활용하여 비즈니스를 최적화하고 있습니다. API는 가치를 실현하고 추가 서비스를 제공하는 방법이 되었습니다.

일반적인 인기에도 불구하고 모든 API가 성공하는 것은 아닙니다. API의 채택과 사용은 API의 성공을 좌우합니다. 채택률을 높이려면 API를 쉽게 찾고 사용할 수 있어야 합니다.

이를 수행하는 가장 좋은 방법은 API를 자세히 문서화하는 것입니다. 여기에는 중요한 구성 요소를 더 쉽게 이해할 수 있도록 자세히 설명하는 것이 포함됩니다. API 문서에 포함해야 하는 일부 구성요소를 알아보세요.

API 문서는 API를 자세히 설명하는 기술 콘텐츠입니다. API 작업에 필요한 모든 정보가 포함된 매뉴얼입니다. 이 문서에서는 API 수명 주기와 해당 구성 요소 통합 및 사용에 대한 지침을 다룹니다.

API 문서에는 리소스 설명, 엔드포인트, 메서드, 요청 및 응답 예제가 포함되어 있습니다. 또한 사용자에게 통합 방법을 보여주는 실용적인 가이드와 튜토리얼이 포함될 수도 있습니다. 각 섹션을 탐색하면 사용자는 API 통합 및 사용에 대한 확실한 이해를 얻을 수 있습니다.

Google Docs와 같은 편집기는 한때 전문 API 문서에 널리 사용되었습니다. 요즘에는 Document 360, Confluence, GitHub Pages와 같은 고급 도구가 있습니다. 이러한 도구는 더 쉬운 작업 흐름을 위해 텍스트와 코드를 통합하는 데 도움이 됩니다.

API 문서화의 첫 번째 단계는 사용자에게 API 내용을 알리는 것입니다. 제공하는 리소스 유형에 대한 정보를 포함합니다. API에는 일반적으로 반환되는 다양한 리소스가 있으므로 사용자는 필요한 것을 요청할 수 있습니다.

설명은 간단하며 일반적으로 리소스를 설명하는 1~3개의 문장으로 구성됩니다. 사용 가능한 리소스, 엔드포인트 및 각 엔드포인트에 연결된 메서드를 설명합니다. API 개발자로서 귀하는 해당 구성 요소, 기능 및 사용 사례를 가장 잘 설명합니다.

다음은 Airbnb API 설명의 예입니다.

API는 수천 건의 요청과 엄청난 양의 데이터를 처리합니다. 인증은 API 및 사용자의 데이터를 해커로부터 보호하는 방법 중 하나입니다. API 인증은 사용자의 신원을 확인하고 리소스에 대한 액세스 권한을 부여합니다.

엔드포인트 보안을 보장하는 방법에는 여러 가지가 있습니다. 대부분의 API는 API 키를 사용합니다. 이는 사용자가 웹사이트에서 생성하여 인증에 사용할 수 있는 문자열입니다.

API 문서는 사용자에게 자신의 신원을 인증하고 승인하는 방법을 안내해야 합니다. 다음 다이어그램은 Twitter API 인증 정보를 보여줍니다.

이 섹션에서는 리소스에 액세스하는 방법을 보여줍니다. 끝점은 경로의 끝만 표시하므로 해당 이름이 표시됩니다. 이는 끝점이 상호 작용하는 리소스 및 HTTP 메서드(예: GET, POST 또는 DELETE)에 대한 액세스를 보여줍니다.

하나의 리소스에는 다양한 엔드포인트가 있을 수 있습니다. 각각 다른 경로와 방법을 사용합니다. 엔드포인트에는 일반적으로 목적과 URL 패턴에 대한 간략한 설명이 있습니다.

다음 코드 샘플은 Instagram의 GET 사용자 엔드포인트를 보여줍니다.

사용자가 무엇을 기대하는지 알 수 있도록 요청 및 응답 형식을 문서화해야 합니다. 요청은 리소스를 요청하는 클라이언트의 URL이고 응답은 서버의 피드백입니다.

다음은 LinkedIn API에 보낼 수 있는 샘플 요청입니다.

반환할 수 있는 샘플 응답은 다음과 같습니다.

또한 엔드포인트에 전달할 수 있는 옵션인 엔드포인트의 매개변수를 문서화해야 합니다. 매개변수는 응답으로 반환되는 데이터의 양이나 유형을 지정하는 ID 또는 숫자일 수 있습니다.

헤더, 경로, 쿼리 문자열 매개변수를 포함하여 다양한 유형의 매개변수가 있습니다. 엔드포인트에는 다양한 유형의 매개변수가 포함될 수 있습니다.

일부 매개변수를 HTTP 요청 헤더로 포함할 수 있습니다. 일반적으로 API 키와 같은 인증 목적으로 사용됩니다. 다음은 API 키가 포함된 헤더의 예입니다.