API 뜻, 앱끼리 정보를 주고받고 작업을 실행하는 규칙

작성자:

API는 프로그램이 다른 프로그램의 기능을 사용할 수 있게 정해 놓은 연결 규칙입니다. 사람은 화면의 버튼과 입력창을 이용하지만, 프로그램은 API가 정한 형식에 맞춰 필요한 기능을 요청합니다. API는 특정 회사의 제품 이름도, 인공지능만 사용하는 기술도 아닙니다.

웹서비스 사이에서 쓰는 API가 널리 알려져 있지만 범위는 더 넓습니다. MDN은 브라우저가 카메라·위치 정보 등의 기능을 제공하는 경우도 API의 예로 설명합니다. 이 글에서는 기업 서비스 연동에 자주 등장하는 웹 API를 중심으로 살펴봅니다.

이 글의 목차

화면을 대신 눌러 주는 것과 무엇이 다를까?

화면 자동화는 프로그램이 사람처럼 버튼을 찾고 입력하는 방식입니다. API 연동은 서비스가 공개한 기능을 정해진 형식으로 직접 호출합니다. 같은 글 등록 업무라도 관리자 화면을 거쳐 입력할 수도 있고, 글 등록용 API에 제목과 본문을 보낼 수도 있습니다.

워드프레스의 공식 API는 글 생성, 개별 글 조회, 수정, 삭제를 구분합니다. 글 생성에는 제목과 본문 외에도 글 상태, 작성자, 대표 이미지, 카테고리, 태그 등의 항목이 있습니다. 화면에서 보던 업무를 컴퓨터가 처리할 수 있는 데이터 항목으로 나눈 구조입니다.

여기서 API를 사용한다는 사실만으로 글이 공개되는 것은 아닙니다. 워드프레스에는 공개, 예약, 임시글, 검토 대기, 비공개 등의 상태가 따로 있습니다. 어떤 기능에 어떤 값을 보내는지가 실제 작업을 결정합니다.

요청에는 주소와 작업 내용이 함께 들어간다

HTTP는 웹에서 요청과 응답을 주고받는 통신 규약입니다. 요청하는 쪽을 클라이언트, 요청을 처리해 답하는 쪽을 서버라고 부릅니다. 웹 API에서 클라이언트는 브라우저일 수도 있고 자동화 프로그램일 수도 있습니다.

요청 주소는 기능을 호출할 위치를 가리킵니다. 이런 접점을 엔드포인트라고 합니다. 주소만 보내는 것이 아니라 어떤 작업을 할지, 어떤 데이터를 사용할지 등도 전달합니다. 응답에는 처리 결과를 나타내는 정보와 반환 데이터가 들어갑니다.

워드프레스에서는 글 목록 주소와 특정 글의 주소를 구분하고, 같은 글의 조회와 수정도 요청 방식으로 구분합니다. 그래서 ‘사이트에 연결됐다’는 것과 ‘원하는 글이 수정됐다’는 것은 다른 결과입니다. 연결은 통신이 가능하다는 뜻이고, 수정은 특정 대상에 대한 작업이 수행됐다는 뜻입니다.

인증과 권한은 별도의 조건이다

인증은 요청자가 누구인지 확인하는 절차이고, 권한은 그 요청자가 어떤 일을 할 수 있는지에 관한 조건입니다. 로그인에 성공한 사용자라도 모든 글을 수정하거나 사이트 설정을 바꿀 수 있는 것은 아닙니다.

워드프레스는 외부 프로그램용 인증 방법으로 애플리케이션 비밀번호를 설명합니다. 일반 로그인 비밀번호를 다른 프로그램에 반복해서 제공하는 대신 별도의 인증정보를 사용하는 방식입니다. 그렇다고 새 비밀번호를 만들면 계정의 역할보다 더 큰 권한이 생기는 것은 아닙니다.

공개된 자료를 읽는 기능과 개인 자료를 수정하는 기능은 요구 조건이 다를 수 있습니다. API가 공개돼 있다는 말은 사용 방법이 알려져 있다는 뜻일 수 있으며, 모든 데이터가 누구에게나 공개됐다는 뜻과는 구분됩니다.

응답을 못 받았다고 작업도 실패한 것은 아니다

프로그램이 요청을 보낸 뒤 통신이 끊어지면 결과가 애매해질 수 있습니다. 서버가 작업을 수행하지 못했을 수도 있지만, 작업은 끝났고 결과를 알려 주는 응답만 전달되지 못했을 수도 있습니다.

결제처럼 같은 작업을 두 번 수행하면 문제가 생기는 기능에서는 이 구분이 중요합니다. Stripe는 동일 요청의 재시도를 구분하기 위해 멱등성 키를 받습니다. 멱등성은 같은 요청을 반복했을 때 의도한 효과가 중복해서 발생하지 않도록 하는 성질입니다.

Stripe의 설명에서는 특정 키로 시작한 요청 결과를 저장하고 같은 키의 후속 요청에 같은 결과를 돌려줍니다. 단, 키 보관 기간과 검증 실패 등 세부 조건이 있습니다. 모든 API가 이 장치를 제공하는 것은 아니며, 다른 서비스에 임의의 키를 붙인다고 같은 기능이 생기지는 않습니다.

이 때문에 API 연동은 ‘요청 전송’만으로 끝나지 않습니다. 응답 확인과 실제 대상 상태 확인, 같은 작업을 다시 보낼 때의 처리 방식까지 포함됩니다. 자동화에서 연결 성공과 업무 완료를 구분하는 이유입니다.

호출 제한은 오류가 아니라 서비스 운영 규칙일 수 있다

API에는 일정 시간 동안 보낼 수 있는 요청의 제한이 있을 수 있습니다. GitHub는 서비스를 여러 이용자가 사용할 수 있도록 요청량을 제한한다고 설명합니다. 인증 방식과 사용하는 기능에 따라 한도가 달라지고, 동시에 과도한 요청을 보내는 경우에도 별도의 제한이 적용됩니다.

공식 문서에는 응답 헤더를 통해 현재 한도와 남은 요청량, 한도가 초기화되는 시각을 확인하는 항목이 나옵니다. 헤더는 본문 외에 함께 전달되는 통신 정보입니다. 요청이 거절됐다고 항상 아이디나 비밀번호가 틀린 것은 아닙니다.

따라서 API의 작동 가능 여부는 단순한 연결뿐 아니라 호출 속도와 현재 사용량에도 영향을 받습니다. 실제 자동화 프로그램에는 요청 제한과 일시적인 장애를 구분하는 처리가 들어갑니다.

계속 물어보는 방식과 알림을 받는 방식

새로운 일이 생겼는지 API를 주기적으로 호출해 확인하는 방식을 폴링이라고 부릅니다. 반면 웹훅은 특정 사건이 발생했을 때 서비스가 미리 정한 주소로 정보를 보내는 방식입니다.

GitHub 웹훅에서는 코드가 올라오거나 검토 요청에 변화가 생기는 등의 사건을 구독할 수 있습니다. 사건이 생기면 GitHub가 등록된 주소에 HTTP 요청을 보냅니다. 받는 프로그램은 이 정보를 이용해 알림이나 다른 업무를 이어갑니다.

두 방식의 차이는 데이터를 가져오는 계기입니다. 폴링은 받는 쪽이 물어보고, 웹훅은 사건을 가진 쪽이 알립니다. 웹훅이 등록돼 있어도 받는 프로그램이 해당 정보를 처리하도록 구성돼 있어야 실제 업무가 이어집니다.

조회가 성공했는데 자료 일부만 보이는 이유

API가 정상 응답을 보냈다는 사실과 전체 자료를 돌려줬다는 사실도 다릅니다. 결과가 많으면 여러 페이지로 나누어 보내는 방식이 사용됩니다. 이를 페이지 나누기, 또는 페이지네이션이라고 합니다. 웹사이트 목록에 다음 페이지가 있는 것처럼 API 결과에도 이어서 받을 부분이 있을 수 있습니다.

GitHub의 공식 예시는 한 저장소에 열린 이슈가 1,600개 넘게 있어도, 한 번의 기본 목록 요청에서는 30개만 반환할 수 있다고 설명합니다. 이슈는 오류나 작업 내용을 기록한 항목입니다. 반환된 30개가 잘못된 데이터인 것은 아니지만, 이를 전체 개수라고 보면 결과 해석이 틀어집니다.

GitHub는 응답의 Link 헤더에 다음 페이지 등의 주소를 제공하는 방식을 설명합니다. 일부 기능에서는 한 페이지당 항목 수도 조절할 수 있습니다. 따라서 API로 목록을 가져오는 작업에는 첫 응답을 받는 일과 남은 페이지까지 수집하는 일이 나뉩니다. 이 숫자는 GitHub 문서의 예시이며 모든 API의 기본 한도가 30개라는 뜻은 아닙니다.

같은 알림이 두 번 오거나 순서가 바뀔 수도 있다

웹훅은 변화가 생겼을 때 알림을 보내지만, 알림이 업무 순서대로 딱 한 번씩 도착한다고 보장되는 것은 아닙니다. Stripe는 생성된 순서대로 이벤트가 전달되는 것을 보장하지 않는다고 명시합니다. 같은 이벤트가 여러 번 전달될 가능성도 별도로 설명합니다.

공식 문서에는 구독 생성과 청구서 생성, 청구서 결제 등의 이벤트가 한 흐름에서 발생하는 예시가 있습니다. 받는 시스템이 결제 알림을 먼저 받았다고 해서 구독이나 청구서가 만들어지는 과정이 없었다는 뜻은 아닙니다. 필요할 때 해당 객체를 API로 조회하는 과정이 알림 처리와 연결됩니다.

여기서 객체는 구독이나 청구서처럼 서비스가 관리하는 데이터 한 건입니다. 이벤트는 그 데이터와 관련해 어떤 일이 발생했는지를 알리는 기록입니다. 대상의 현재 상태와 과거 변화 알림을 구분하면 순서가 바뀌어 도착하는 상황을 이해할 수 있습니다.

또한 동일 이벤트의 재전달과 실제로 새 결제가 생긴 경우는 다릅니다. Stripe는 처리한 이벤트의 식별자를 기록해 중복 전달을 구분하는 방식을 설명합니다. 앞서 본 멱등성 키가 보내는 요청의 중복 효과를 다루는 장치라면, 이벤트 식별자 확인은 받는 알림의 중복 처리를 다루는 장치입니다. 둘은 연결된 업무의 서로 다른 방향을 담당합니다.

API 연결이 자동화를 완성하는 것은 아니다

API는 기능을 호출하는 통로와 규칙을 제공합니다. 어떤 자료를 가져올지, 어떤 조건에서 실행할지, 결과가 불확실하면 어떻게 처리할지까지 자동으로 결정해 주는 것은 아닙니다.

하나의 업무에는 조회, 자료 가공, 사용자 승인, 등록, 결과 확인 등 여러 단계가 있을 수 있습니다. API는 그중 외부 서비스와 주고받는 부분을 담당합니다. 인공지능을 연결하더라도 서비스의 권한과 호출 조건은 그대로 존재합니다.

API를 이해한다는 것은 복잡한 코드를 모두 읽는다는 뜻보다, 어떤 프로그램이 어떤 권한으로 무엇을 요청하고 어떤 결과를 확인하는지 구분하는 데 가깝습니다. 이 구조를 알면 ‘API 연동 가능’이라는 설명이 제공하는 기능과 아직 별도로 구성해야 할 업무를 나눠 볼 수 있습니다.

참고자료