API 모니터링에서는 어떤 HTTP 메서드를 쓸 수 있나요?

GET, POST, PUT, DELETE, PATCH, HEAD를 모두 지원합니다. 각 모니터마다 메서드를 설정할 수 있습니다. write 엔드포인트(POST/PUT/PATCH)의 경우 요청 본문도 JSON 문자열이나 form data로 지정 가능합니다.

JSON 어서션은 어떻게 동작하나요?

JSON 경로(예: data.status 또는 results[0].id)와 예상 값을 지정합니다. 모니터가 응답을 받아 JSON으로 파싱해 해당 경로를 추출, 예상 값과 비교합니다. 다를 경우 "assertion failed"라는 오류와 함께 실제 값을 표시해 체크가 실패로 기록됩니다.

인증 헤더를 포함해서 전송할 수 있나요?

네, 커스텀 HTTP 헤더는 모니터별로 자유롭게 설정 가능합니다 — Authorization 토큰, API 키, content-type 등 모두 입력할 수 있습니다. 헤더 값은 데이터베이스에 안전하게 암호화되어 저장됩니다. Basic Auth용으로는 별도 username/password 필드를 제공하며, 자동으로 요청에 서명합니다.

API가 200과 에러 페이로드를 반환하면?

흔한 케이스입니다: API는 HTTP 200을 반환하나, 본문에 {"status":"error"}가 포함되어 있습니다. 단순 업타임 체크는 정상으로 보므로, JSON 어서션 status == "ok"를 설정하세요 — 어서션이 실패하면 HTTP가 200이어도 DOWN으로 보고됩니다.

rate limit이 있는 API는 어떻게 관리하나요?

API 제한에 맞춰 체크 인터벌을 조정하세요(예: 시간당 12회 호출이 가능한 API라면 5분 인터벌). 모니터 1회 체크는 각 지역당 1회로 계산됩니다. 멀티리전 체크는 그만큼 API 호출 수가 늘어나니, 제한이 엄격하다면 싱글 리전만 사용하세요.

API 모니터링 — HTTP, JSON, Bearer 인증

REST API는 200 OK 확인만으로는 충분하지 않습니다. 메서드, 헤더, 본문, JSON 경로 및 정확한 응답 코드를 검증하세요.

API가 자체 모니터링이 필요한 이유

API는 /api/ 경로 아래의 단순한 페이지가 아닙니다. 이는 계약입니다. HTTP 메서드는 중요합니다 - GET과 POST는 의미가 다릅니다. 헤더는 인증, 콘텐츠 협상, 멱등성 키를 담습니다. 요청 본문은 입력값입니다. 응답 코드는 중요합니다(401, 403, 422 - 각각이 다른 이야기를 합니다). 응답 본문에는 구조가 있으며, 이는 통합자(integrator)들이 의존하는 JSON 경로입니다. 단순한 가용성 체크(업타임 체크)는 GET으로 URL만 호출해 대부분의 API 다운 시나리오를 놓치게 됩니다: 잘못된 JSON이라도 200을 반환할 수 있고, 인증 엔드포인트가 잘못된 정보를 허용할 수도 있습니다. 웹훅이 깨진 페이로드 스키마를 갖거나, 엔드포인트가 200을 반환하지만 내부에 "status": "error"가 들어 있을 수도 있습니다.

API 모니터링은 이러한 문제를 해결하여, 요청의 모든 부분과 응답 검증의 모든 부분을 직접 제어할 수 있게 해줍니다. 실제 통합자가 호출하는 것과 똑같은 방식으로 요청을 설정할 수 있습니다 - 동일한 메서드, 동일한 헤더, 동일한 바디, 동일한 인증 - 그리고 성공의 의미도 정확히 지정할 수 있습니다 - 정확한 코드, JSON 경로의 값, 응답 시간 임계값, 크기 한계까지.

요청 설정

DiagnoSEO Uptime Monitoring에서 각 API 모니터마다 다음과 같이 설정할 수 있습니다:

HTTP 메서드: GET, POST, PUT, PATCH, DELETE, HEAD. 통합자들이 사용하는 방법을 선택하세요.
커스텀 헤더: JSON 객체로 입력, 예: {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. OAuth, JWT, API 키, 컨텐츠 협상 등을 테스트할 때 표준입니다.
요청 본문: 임의의 문자열 - JSON, XML, form-encoded, 일반 텍스트 등. POST/PUT/PATCH/DELETE 사용 시 함께 전송됩니다.
Basic 인증: 엔드포인트가 보호되어 있다면 사용자명과 비밀번호를 입력합니다.
예상 상태 코드: 리스트 또는 범위. 기본값은 200-399이지만, 단일 코드로 제한할 수도 있고(예: 생성 엔드포인트에 대해 정확히 201) 특정 코드만 허용할 수도 있습니다(예: 200,202,204).

상태 확인은 최대 5번의 리디렉션을 따라가고, gzip을 디코딩하며, Content-Type을 파싱하여 JSON을 감지합니다. 각 확인 시 실제 코드, 응답 시간, 크기 및 오류를 기록합니다. 여러 번 연속 실패(설정 가능, 기본 2회)는 인시던트를 트리거합니다.

JSON path 어서션

상태 코드만으로는 많은 API를 충분히 확인할 수 없습니다. health 엔드포인트가 200을 반환하면서도 본문이 {"status": "degraded", "db": "down"}일 수 있습니다 - 여전히 200이지만, 반드시 알아야 하는 상황입니다. 가격 API는 본문에서 data.price가 null로 떨어져도 200을 반환할 수 있습니다. 검색 API는 인덱스에 문제가 생겨 results: []로 200을 반환할 수도 있습니다.

이럴 땐 JSON path 어서션을 설정하세요. 경로(예: data.status 또는 health.checks.db)와 기대값(예: healthy, true, 또는 구체적인 숫자)을 지정합니다. 각 점검마다 응답이 JSON으로 디코딩되고, 해당 경로의 값이 비교됩니다. 일치하지 않으면 HTTP 상태 코드와 관계없이 체크가 실패로 처리됩니다.

경로 문법은 점 표기법에 대괄호 사용 방식입니다: data.items[0].id가 동작하며, users.john.email도 마찬가지입니다. 어서션 값은 문자열로 비교되므로, "true"는 불리언 true와 일치하고, 숫자도 문자열과 숫자 모두에서 일치합니다.

인증 패턴

가장 흔한 두 가지 인증 방식이 기본적으로 지원됩니다. Bearer 토큰(OAuth, JWT, API 키)의 경우, headers 필드에 {"Authorization": "Bearer eyJhbGciOi..."}를 사용하면 됩니다. 토큰은 모니터 설정 내에 저장되어, 매 확인마다 자동 전송됩니다. Basic 인증은 사용자명/비밀번호 전용 필드가 있으므로, 이 정보를 저장해 표준 헤더로 결합됩니다.

만약 인증이 요청별 서명이나 토큰 갱신이 필요하다면 더 복잡해집니다. 이땐 두 가지 방안이 있습니다: (1) 모니터링용 장수 토큰(서비스 계정용)을 별도로 생성하거나, (2) 인증이 필요 없는 health 엔드포인트를 마련하여 실제 보호된 엔드포인트의 상태를 반영하게 하고 해당 엔드포인트를 모니터링합니다. 대부분의 현대적 API는 기본적으로 이 방법을 지원합니다.

다른 모니터 타입과 결합

각 API 엔드포인트마다 API 모니터는 호출 동작을 확인하고, 별도의 핑 또는 포트 모니터는 호스트의 생존 여부를 검사합니다. 같은 호스트 이름에 대해 SSL/도메인 모니터는 인증서 및 등록 문제를 포착합니다. DNS 서브모니터는 레코드 변경(스푸핑 의심)을 감시합니다. 네 가지 모니터를 API에 결합하면 최소 겹침으로 전체 그림을 볼 수 있습니다.

설정 방법

도구를 열고 "모니터 추가"를 클릭한 뒤 타입으로 "API"를 선택하세요. URL을 붙여넣고, 고급 섹션을 엽니다. 메서드를 선택하고 헤더를 JSON으로 붙여넣으며, 필요하면 본문을 붙여넣고, Basic 인증을 사용 중이면 계정을 입력합니다. 예상 코드를 입력하세요(예: 200 또는 200,201). JSON path 어서션이 필요한 경우 추가합니다. 인터벌과 확인 임계값을 설정하고 저장하세요. 다음 주기부터 모니터가 실제 통합자처럼 API를 호출하여 응답을 검증하고, 회귀 즉시 알람을 울립니다.

자주 묻는 질문

API 모니터링에서는 어떤 HTTP 메서드를 쓸 수 있나요?
GET, POST, PUT, DELETE, PATCH, HEAD를 모두 지원합니다. 각 모니터마다 메서드를 설정할 수 있습니다. write 엔드포인트(POST/PUT/PATCH)의 경우 요청 본문도 JSON 문자열이나 form data로 지정 가능합니다.
JSON 어서션은 어떻게 동작하나요?
JSON 경로(예: data.status 또는 results[0].id)와 예상 값을 지정합니다. 모니터가 응답을 받아 JSON으로 파싱해 해당 경로를 추출, 예상 값과 비교합니다. 다를 경우 "assertion failed"라는 오류와 함께 실제 값을 표시해 체크가 실패로 기록됩니다.
인증 헤더를 포함해서 전송할 수 있나요?
네, 커스텀 HTTP 헤더는 모니터별로 자유롭게 설정 가능합니다 — Authorization 토큰, API 키, content-type 등 모두 입력할 수 있습니다. 헤더 값은 데이터베이스에 안전하게 암호화되어 저장됩니다. Basic Auth용으로는 별도 username/password 필드를 제공하며, 자동으로 요청에 서명합니다.
API가 200과 에러 페이로드를 반환하면?
흔한 케이스입니다: API는 HTTP 200을 반환하나, 본문에 {"status":"error"}가 포함되어 있습니다. 단순 업타임 체크는 정상으로 보므로, JSON 어서션 status == "ok"를 설정하세요 — 어서션이 실패하면 HTTP가 200이어도 DOWN으로 보고됩니다.
rate limit이 있는 API는 어떻게 관리하나요?
API 제한에 맞춰 체크 인터벌을 조정하세요(예: 시간당 12회 호출이 가능한 API라면 5분 인터벌). 모니터 1회 체크는 각 지역당 1회로 계산됩니다. 멀티리전 체크는 그만큼 API 호출 수가 늘어나니, 제한이 엄격하다면 싱글 리전만 사용하세요.

API 모니터링