API(Application Programming Interface)란 프로그램이 다른 프로그램의 기능이나 데이터를 사용할 수 있도록 정한 인터페이스입니다. 쉽게 말해, 어떤 방식으로 기능을 호출하고 어떤 결과를 받을지 정한 약속입니다. MDN의 API 설명에서도 프로그램 사이의 계약으로 소개합니다.
1. API는 어디에 쓰일까요?
쇼핑몰에서 배송 상태를 확인하거나, 앱에서 지도와 날씨 정보를 보여줄 때 API를 활용할 수 있습니다. 다른 시스템이 제공하는 기능을 정해진 방식으로 호출하면, 그 시스템의 내부 구현을 모두 알지 않아도 기능을 이용할 수 있습니다.
식당에 비유하면 메뉴와 주문 규칙에 가깝습니다. 손님이 메뉴에 맞춰 주문하듯 프로그램도 약속한 입력을 전달합니다.
API에는 운영체제나 라이브러리의 기능을 호출하는 인터페이스도 있습니다. 여기서는 HTTP로 요청과 응답을 주고받는 웹 API를 예로 살펴보겠습니다. HTTP의 요청·응답 구조를 알아두면 흐름을 이해하기 쉽습니다.
2. 주문 조회로 보는 요청과 응답
쇼핑몰에서 주문 상세 화면을 연다고 가정해 보겠습니다. 앱은 서버에 주문 조회를 요청하고, 서버는 요청과 권한을 확인한 뒤 결과를 돌려줍니다. 앱은 받은 데이터를 화면에 표시합니다.
아래 주소·토큰·데이터는 설명용 가상 예시입니다. 실제로 호출할 수 있는 서버가 아닙니다.
요청: 이 주문의 상태를 알려주세요
GET https://example.invalid/v1/orders/ORDER-DEMO-001
Authorization: Bearer <ACCESS_TOKEN>| 요청에서 볼 부분 | 의미 |
|---|---|
| GET | 정보를 조회하는 HTTP 메서드 |
| /v1/orders/ORDER-DEMO-001 | 조회할 주문을 가리키는 경로 |
| Authorization | 이 예시에서 인증 정보를 전달하는 헤더 |
성공 응답 · 200 OK
{
"orderId": "ORDER-DEMO-001",
"status": "SHIPPED"
}이 예시에서는 SHIPPED를 ‘배송 중’으로 정했습니다. 앱은 이 값을 읽어 배송 상태를 표시할 수 있습니다. JSON은 데이터를 표현하는 형식이며, 응답 형식은 API마다 다를 수 있습니다.
요청이 항상 성공하는 것은 아닙니다. 인증이 필요하면 401, 요청한 리소스를 찾을 수 없으면 404 같은 상태를 받을 수 있습니다. HTTP 상태 코드 설명을 참고하되, 구체적인 실패 조건과 처리 방법은 해당 API 문서에서 확인하세요.
3. API 명세서가 필요한 이유
위 예시만으로도 질문이 생깁니다. 주문 번호는 필수일까요? status에는 어떤 값이 올까요? 다른 사람의 주문을 조회하면 어떻게 될까요?
API 명세서는 이런 사용 규칙을 문서로 정리한 것입니다. 호출 주소, 인증 방식, 입력값, 성공·오류 응답을 적어 두면 개발자와 연동 담당자가 같은 기준으로 작업할 수 있습니다.
예를 들어 서버가 status를 deliveryStatus로 바꾸면 기존 필드를 읽던 화면을 수정해야 할 수 있습니다. 변경한 필드와 적용 시점을 함께 공유해야 하는 이유입니다.
4. 처음 읽는 API 문서, 세 가지만 확인하세요
팀에서 사용하는 API 하나를 골라 다음 내용을 한 줄씩 적어 보세요.
- 무엇을 하는가: 조회·생성 등 어떤 기능이며, 어느 주소로 호출하는가?
- 무엇을 보내는가: 인증 정보와 필수 입력값은 무엇인가?
- 무엇을 받는가: 성공 결과와 실패했을 때의 처리 방법은 무엇인가?
직접 정리하려면 API 작성 방법과 명세서 양식을, 요청을 확인할 도구가 필요하면 API 툴 비교 글을 이어서 읽어보세요.
이 글은 API 문서 도구를 만드는 스펙브릿지 팀이 작성했습니다. 팀 문서에 적용하려면 스펙브릿지의 문서 작성 기능과 변경 검토·배포·공유 흐름을 살펴보세요.