API 소개 자료

템플릿 소개

이 자료가 답해야 하는 질문

API를 외부에 소개하는 자리에서 상대가 알고 싶은 것은 엔드포인트 목록이 아닙니다. 우리 시스템에 붙일 수 있는지, 붙이는 데 얼마나 걸리는지, 한도를 넘기면 어떻게 되는지 세 가지입니다. 이 파일은 그 순서로 짜여 있습니다. 표지와 목차, 간지 4장과 본문 4장, 비교 슬라이드, 핵심 지표, 추이 분석, 마무리로 14장입니다. 요청·응답 예시 전문은 이 발표 자료가 아니라 문서 사이트에 두고, 여기서는 링크만 걸어 두는 편이 낫습니다.

목차 일곱 줄이 모두 화면을 갖고 있습니다

2장 목차는 빠른 시작 · 인증 방식 · 엔드포인트 · 호출 한도 · v1 과 v2 · 핵심 지표 · 추이 분석 순으로 왼쪽에 1부터 7까지 번호가 붙어 있습니다. 앞 네 항목은 간지와 본문이 한 쌍씩 붙어 3장부터 10장까지 이어지고, 뒤 세 항목은 11장 비교 슬라이드 · 12장 지표 카드 · 13장 막대 그래프로 각각 한 장입니다. 목차 어느 줄을 짚어도 보여 줄 화면이 있으니 발표 전에 확인할 것은 순서가 아니라 각 장의 값이 우리 API 스펙과 맞는지입니다. 오류 코드나 SDK·문서처럼 이 파일에 없는 주제를 넣어야 한다면 간지와 본문 한 쌍(9·10장)을 복제해 SECTION 번호를 05·06으로 이어 붙이고 목차에도 줄을 더하세요. 반대로 15분짜리 자리라면 호출 한도까지만 발표하고 뒤 세 장은 배포본으로 넘겨도 흐름은 끊기지 않습니다.

본문 네 장에 들어갈 것

본문은 큰 제목, 한 줄 설명, 항목 세 개 구조입니다. 네 장의 기본 제목과 채울 내용은 이렇습니다.

• 4장 빠른 시작 — “키 발급부터 첫 호출 5분”, “샌드박스 환경 무료 제공”, “예제 요청 복사해서 실행”. 5분이라고 적었다면 실제로 그 시간 안에 끝나는지 한 번 재보고 쓰세요.
• 6장 인증 방식 — “OAuth 2.0 토큰 발급”, “키 교체 주기 90일 권장”, “허용 IP 목록 등록 가능”. 토큰 유효 기간과 갱신 방법을 한 줄 더 붙이면 질문이 줄어듭니다.
• 8장 엔드포인트 — “조회·생성·수정 등 34개”, “응답 형식은 JSON 고정”, “한 번에 최대 200건 반환”. 34개를 나열하지 말고 분류만 남깁니다.
• 10장 호출 한도 — “기본 초당 20회로 제한”, “초과하면 429 코드 반환”, “상향은 담당자 협의 후 적용”. 한도가 키 단위인지 조직 단위인지 밝혀야 합니다.

지표 네 칸에는 측정 조건을 붙입니다

12장에는 공개 엔드포인트 34개, 호출 성공률 99.95%, 평균 응답 시간 68ms, 초당 호출 한도 20회가 들어 있습니다. 값만 쓰면 반드시 되물음이 옵니다. 측정 기간과 구간을 같이 적으세요. 예: 99.95% / 최근 90일, 계획 점검 제외. 예: 68ms / p50, 서울 리전. p50과 p95는 체감이 크게 다르므로 어느 쪽인지 밝히는 게 안전합니다. 20회와 34개는 10장·8장 본문에도 같은 값으로 나오니 한쪽을 고치면 나머지도 함께 고쳐야 합니다.

추이 막대는 올라가는 값입니다

13장 추이 분석은 v1.0 12, v2.0 21, v3.0 29, v4.0 34로 버전이 올라갈수록 값이 커지는 막대입니다. 마지막 34가 12장의 공개 엔드포인트 수와 같으니, 이 그래프는 공개 범위가 넓어진 과정을 보여주는 자리입니다. 응답 시간이나 오류율처럼 낮을수록 좋은 지표를 여기에 넣으면 막대가 오른쪽으로 커지면서 반대 메시지가 됩니다. 그런 지표를 쓰고 싶다면 값 순서를 뒤집고 축 아래에 낮을수록 좋다는 문구를 적어 두세요.

되물음을 부르는 구성

• 엔드포인트 34개를 전부 나열한다 — 훑고 나면 무엇이 강점인지 남지 않습니다.
• 성공률만 쓰고 실패했을 때를 뺀다 — 검토자가 확인하는 것은 429와 5xx가 났을 때의 재시도 지침과 통지 경로입니다.
• 11장 v1 과 v2의 요청 한도(분당 60회 → 600회)와 인증 방식(고정 API 키 → OAuth 2.0)을 실제 스펙으로 바꾸지 않고 두는 것 — 개발자는 이 두 줄을 먼저 확인하므로 레퍼런스 문서와 어긋나면 나머지 설명까지 신뢰를 잃습니다.
• 12장 지표와 13장 막대의 마지막 값을 따로 관리하는 것 — 둘 다 34로 맞춰져 있어 한쪽만 고치면 발표 중에 곧바로 지적을 받습니다.