Our Dots External API

Base URL

모든 external API의 기준 URL은 https://our.co.kr/api/v1/external입니다. 로컬 또는 프리뷰에서도 path 구조는 동일하게 유지합니다.

GET https://our.co.kr/api/v1/external/ping
GET https://our.co.kr/api/v1/external/lectures?page=1&pageSize=20
GET https://our.co.kr/api/v1/external/jireh/problems?q=도시&page=1&pageSize=20

인증과 키 발급

요청에는 Authorization: Bearer {keyId}.{secret} 헤더를 보냅니다. 대체 형식으로 X-Api-Key와 X-Api-Secret 헤더를 함께 보낼 수 있습니다.

API 키는 관리자 화면 our.co.kr/admin에서 발급합니다. 발급 시 client 정보, 라벨, scope, PII 허용 여부, 허용 IP/CIDR을 함께 등록합니다.

Authorization: Bearer od_xxxx.{secret}
X-Api-Key: od_xxxx
X-Api-Secret: {secret}

공통 오류 형식

오류 응답은 항상 { "error": { "code", "message" } } 형태입니다. endpoint별 쿼리 검증 실패는 400 INVALID_QUERY를 반환합니다.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API 키가 필요합니다."
  }
}

비식별 정책

기본 응답은 개인정보를 비식별합니다. 이름은 박*수, 학번·식별번호는 208***50 형태로 줄이고, 전화번호와 이메일은 일부만 남겨 마스킹합니다.

PII 원문은 키가 allowPii=true이고 요청 IP가 키의 허용 IP/CIDR에 포함될 때만 반환됩니다. 그 외에는 PII 허용 키여도 403 FORBIDDEN입니다.

• OurDots 강의·댓글·강사 이름은 기본적으로 마스킹됩니다.
• Jireh 응답은 name, email, phone, mobile, studentNumber, idNumber, birth 계열 필드를 재귀적으로 마스킹합니다.
• Jireh의 regionName, topicName, missionName처럼 사람이 아닌 명칭 필드는 이름 마스킹 대상에서 제외합니다.

scope 목록

scope는 키 단위로 부여합니다. /ping은 키 유효성만 확인하므로 scope가 필요하지 않습니다.

• ourdots.lectures — 강의 목록과 상세
• ourdots.comments — 강의 댓글과 질문/답글
• ourdots.creators — 강사 공개 프로필
• jireh.problems — Jireh 문제 목록과 상세
• jireh.missions — Jireh 미션 목록
• jireh.innovations — Jireh 혁신 프로젝트 상세
• jireh.impacts — Jireh 임팩트 목록

빠른 시작: ping

/ping은 credential이 유효한지 확인하고, 성공 시 사용량 적립과 last used 갱신을 수행합니다. 성공 응답은 { ok: true, keyId, pii }입니다.

curl -sS https://our.co.kr/api/v1/external/ping \
  -H "Authorization: Bearer od_xxxx.{secret}"

{
  "ok": true,
  "keyId": "od_xxxx",
  "pii": false
}

모든 external API는 IP 기준 120 req/min 제한을 공유합니다. 제한 초과 시 Retry-After 헤더와 429 RATE_LIMITED를 반환합니다.