RESTful API 개요

작성자: admin 작성일: 2025-07-08 수정일: 2025-07-09
API Documentation

Push Manager API

Push Manager API는 웹 푸시 알림을 쉽고 안전하게 발송할 수 있는 RESTful API 서비스입니다. 표준 웹 푸시 프로토콜을 기반으로 하며, VAPID 인증과 강력한 보안 기능을 제공합니다.
Base URL: https://api.pushmanager.kr

주요 기능

  • 단일 및 다중 푸시 알림 발송
  • VAPID 키 자동 생성 및 관리
  • 실시간 발송 통계 및 분석
  • 도메인 기반 Origin 검증
  • Rate Limiting 및 보안 미들웨어
  • 상세한 에러 리포트 및 분류

Authentication (인증)

모든 API 요청은 적절한 인증 헤더가 필요합니다. Push Manager API는 두 가지 인증 방식을 사용합니다.
헤더 용도 설명 필수
X-API-Key 서비스 인증 서비스별로 발급되는 고유 API 키. 푸시 발송 및 통계 조회에 사용 모든 API
Origin 도메인 검증 등록된 사이트 도메인과 일치해야 함. CORS 및 보안 검증에 사용 모든 API
Content-Type 콘텐츠 타입 JSON 요청의 경우 application/json 설정 POST/PUT

인증 예시

// API 요청 헤더
X-API-Key: your-service-api-key-here
Origin: https://your-registered-domain.com
Content-Type: application/json

응답 코드

API는 표준 HTTP 상태 코드를 사용하며, 각 응답에는 상세한 오류 정보가 포함됩니다.
상태 코드 의미 설명
200 OK 성공 요청이 성공적으로 처리됨
201 Created 생성 완료 리소스가 성공적으로 생성됨 (서비스 등록 등)
400 Bad Request 잘못된 요청 요청 데이터가 유효하지 않음 (유효성 검사 실패, 페이로드 크기 초과 등)
401 Unauthorized 인증 실패 API 키가 누락되었거나 유효하지 않음
403 Forbidden 접근 거부 Origin 검증 실패, API 키 비활성화, IP 제한 등
404 Not Found 리소스 없음 요청한 엔드포인트나 리소스가 존재하지 않음
409 Conflict 충돌 이미 등록된 사이트 URL로 중복 등록 시도
413 Payload Too Large 페이로드 크기 초과 요청 크기가 10MB를 초과함
429 Too Many Requests 요청 한도 초과 Rate Limit 초과 (분당 요청 수 제한)
500 Internal Server Error 서버 오류 서버 내부 오류 발생
503 Service Unavailable 서비스 이용 불가 데이터베이스 연결 실패 등 일시적 서비스 장애

표준 에러 응답 형식

{
  "success": false,
  "message": "Error description",
  "code": "ERROR_CODE",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Rate Limiting

API 요청은 다음과 같은 제한이 적용됩니다:
일반 API: API 키당 15분에 1,000회
푸시 발송: API 키당 1분에 100회
다중 푸시: 요청당 최대 1,000개 구독자

API 엔드포인트

푸시 알림

통계 및 분석

문서 검색