IT 시스템블로그 글
웹서비스 API란 무엇인가?
API가 웹서비스에서 서로 다른 서비스와 시스템을 연결하는 방식과 기본 용어를 설명합니다.
API는 프로그램이 다른 프로그램의 기능이나 정보를 정해진 방식으로 사용할 수 있도록 마련한 접점입니다. 사람이 화면의 버튼을 누르듯, 프로그램은 API가 정한 요청과 응답 규칙에 따라 필요한 작업을 주고받습니다.
이 글은 웹서비스 사이에서 데이터를 조회하거나 처리를 요청하는 API를 중심으로 설명합니다. API에는 브라우저 기능을 사용하는 것처럼 다른 종류도 있으므로 모든 API가 외부 인터넷 서비스 연결만 뜻하는 것은 아닙니다.
1. API는 연결의 규칙을 제공합니다
MDN의 API 용어 설명은 소프트웨어가 다른 소프트웨어의 기능·데이터와 상호작용하도록 제공되는 접점이라는 개념을 설명합니다. 웹 API를 검토할 때도 무엇을 요청할 수 있고 어떤 형식으로 결과를 받는지 확인하는 것이 출발점입니다.
예를 들어 내부 시스템이 외부 서비스의 처리 상태를 확인하는 가상 상황을 생각할 수 있습니다. 정해진 대상과 조건으로 조회를 요청하고 결과를 받아 내부 화면에 표시합니다. 이는 구조를 설명하기 위한 예시이며 실제 전산가이의 연동 사례나 제공 범위를 뜻하지 않습니다.
| 기본 용어 | 쉬운 뜻 | 확인할 내용 |
|---|---|---|
| 요청 | 프로그램이 상대에게 보내는 작업 요구 | 대상·행동·필요한 입력 |
| 엔드포인트 | 요청을 받는 주소나 접점 | 실제 환경·경로·허용 작업 |
| 응답 | 상대가 돌려주는 처리 결과 | 데이터 형식·성공과 실패의 의미 |
| 인증·권한 | 누가 어떤 작업을 할 수 있는지 확인 | 자격증명·허용 범위·관리 책임 |
| 제한·오류 | 요청을 처리하지 못하거나 제한하는 조건 | 오류 유형·호출 제한·대응 방식 |
용어를 아는 것만으로 연결이 끝나는 것은 아닙니다. 실제 제공자의 문서와 허용된 시험 환경에서 입력·결과·권한을 확인해야 합니다.
2. 데이터 형식과 업무 의미를 함께 맞춥니다
양쪽 시스템이 같은 이름의 항목을 쓰더라도 의미가 같다는 보장은 없습니다. 상태 값·날짜 기준·식별자·단위·필수 여부를 대조하고 변환 책임을 정합니다. 요청이 성공해도 잘못 해석한 값이 저장되면 업무 결과는 틀릴 수 있습니다.
또한 어느 시스템이 원본인지, 언제 조회하거나 갱신하는지, 변경·취소는 어떻게 전달하는지 합의하세요. 저장 구조가 궁금하다면 데이터베이스의 역할을 함께 확인할 수 있습니다.
3. 실패와 중복을 정상 흐름만큼 검토합니다
응답이 늦거나 연결이 끊겼다고 상대의 처리가 반드시 실패한 것은 아닐 수 있습니다. 무조건 다시 요청하면 중복 처리될 수 있으므로 제공자가 지원하는 결과 확인·중복 방지·재시도 조건을 확인해야 합니다.
| 연결 전 질문 | 정리할 기준 | 시험할 상황 예시 |
|---|---|---|
| 어떤 정보를 주고받는가? | 항목 정의·형식·원본·변환 | 필수 값 누락·알 수 없는 상태 |
| 누가 사용할 수 있는가? | 인증·행동 및 데이터별 권한 | 잘못된 인증·권한 없는 대상 |
| 실패하면 무엇을 하는가? | 오류 분류·재시도·수동 확인 | 연결 실패·지연·부분 처리 |
| 중복을 어떻게 막는가? | 요청 식별·결과 확인 방식 | 같은 요청 반복·응답 유실 |
| 변경은 누가 관리하는가? | 문서·버전·연락·검증 책임 | 응답 형식 변경·종료 안내 |
표는 일반적인 검토 틀이며 특정 API가 이 기능을 제공한다는 의미는 아닙니다. 지원하지 않는 기능은 있다고 가정하지 말고 제한과 대안을 기록하세요.
4. 비밀정보와 운영 책임을 분리해 관리합니다
API 키나 토큰은 일반 안내문·화면·URL·공개 저장소·로그에 노출하지 않습니다. 제공자의 방식에 맞게 서버 측 보관과 접근 통제, 회전·폐기 절차를 확인해야 합니다. 실제 요청 권한이 필요한 작업은 승인된 계정과 환경에서만 시험합니다.
연결 후에도 호출 제한·오류·자료 차이·제공자 변경을 확인할 담당자가 필요합니다. ‘연결 성공’과 업무 전 과정 검증을 구분하고, 정상 처리와 예외를 포함한 검수 기준을 남기세요. 비용이나 사용 한도는 실제 제공자의 현재 조건을 확인해야 하며 임의 수치를 넣지 않습니다.
API 연결 전 체크리스트
자주 묻는 질문(FAQ)
API가 있으면 어떤 시스템이든 바로 연결되나요?
필요한 작업과 데이터가 실제로 제공되는지, 접근 권한과 환경·사용 조건이 맞는지 확인해야 합니다. API 존재만으로 전체 업무 연결이 가능하다고 확정할 수는 없습니다.
API와 데이터베이스는 같은 것인가요?
API는 기능·데이터를 사용하는 접점이고 데이터베이스는 정보를 저장·조회·관리하는 구성입니다. API 뒤에서 데이터베이스를 사용할 수 있지만 같은 개념은 아닙니다.
오류가 나면 계속 다시 호출하면 되나요?
오류 종류와 제공자의 재시도 조건을 확인해야 합니다. 이미 처리된 요청인지 모르는 상태에서 반복하면 중복이나 제한 문제를 만들 수 있습니다. 결과 확인과 중복 방지 방식도 검토하세요.
API 키를 전달하면 연동 검토가 빨라지나요?
일반 문의나 공유 문서에 비밀정보를 넣지 마세요. 먼저 비밀정보를 제외한 문서·필요 작업·시험 범위를 공유하고, 실제 접근은 승인된 안전한 전달·보관 절차로 진행해야 합니다.
핵심 정리
웹 API는 프로그램 사이의 요청과 응답 규칙을 제공합니다. 실제 연결에는 데이터의 의미·권한·실패·중복·운영 조건까지 확인하는 작업이 필요합니다.
연결 목적과 필요한 정보부터 정리해 보세요
연결하려는 업무와 필요한 데이터·공개 문서·현재 제약을 비밀정보 없이 정리해 전산가이 문의하기로 전달해 주세요. 확인할 범위와 시험 조건을 구체화할 수 있습니다.