AI와 API 연동 시작하기

API 정의 Markdown

인증, 엔드포인트·파라미터, 응답 예시, 변경분 동기화, 오류 처리와 언어별 샘플을 한 파일에 담았습니다.

이렇게 사용하세요

1. 1개 파일 다운로드sposerv-api.md를 내려받아 AI 대화에 첨부하거나 프로젝트의 docs 폴더에 저장하세요.
2. 원하는 기능 설명언어, 종목과 저장 방식에 맞게 아래 예시를 수정해 전달하세요.
3. 키는 실행 환경에 입력API 키를 SPOSERV_API_KEY 환경변수에 저장하세요. 다운로드 문서나 AI 대화에 실제 키를 넣을 필요는 없습니다.
4. 개발용으로 확인/me로 이용 상태를 확인한 뒤, 개발용 데이터로 연동과 오류 처리를 점검하세요.

AI에 전달할 요청 예시

Python을 Node.js·PHP·Java·C#으로, SQLite를 원하는 저장소로 바꿔도 됩니다.

첨부한 sposerv-api.md를 API 계약으로 사용해 Python 3 연동 프로그램을 만들어줘.
축구·농구 경기와 배당을 받아 SQLite에 저장하고, 이후 변경된 데이터만 반영해줘.
API 키는 SPOSERV_API_KEY 환경변수, 주소는 SPOSERV_BASE_URL 환경변수에서 읽어줘.
먼저 /me로 이용 상태를 확인하고 개발용 데이터와 라이브 데이터를 분리해줘.
계정 전체 요청 간격 5초 이상, Retry-After, 타임아웃과 제한된 재시도를 처리해줘.
첫 전체 조회 후 query_id와 next_page로 모든 페이지를 받고, sync_complete=true일 때만 checkpoint_ts를 저장해줘.
다음 조회는 all_dates=1과 updated_since_ts를 사용하고, active=false인 가격을 제거해줘.
중복 행은 키로 덮어쓰고 실패한 배치에서는 체크포인트를 전진시키지 마.
한글은 UTF-8, 쿼리는 URL 인코딩하고 키를 로그나 코드에 남기지 마.
실행 방법, 필요한 패키지, .env.example, 모의 응답 테스트도 작성해줘.
문서에 없는 동작은 추측해서 구현하지 말고 확인할 항목으로 적어줘.요청 예시 복사

한글과 시간 인코딩

응답 JSON과 다운로드 문서는 UTF-8입니다. 소스·저장 파일도 UTF-8을 사용하고, 한글 쿼리는 URLSearchParams, urlencode, curl --data-urlencode 등으로 인코딩하세요.

시각의 *_ts는 unix 초, *_at는 한국시간입니다. 날짜의 공백과 +09:00의 +도 인코딩해야 합니다.

curl -G "$SPOSERV_BASE_URL/api/v1/events" \
  -H "X-API-Key: $SPOSERV_API_KEY" \
  --data-urlencode 'sports=football' \
  --data-urlencode 'q=아스널'

SPOSERV_BASE_URL은 https://sposerv.com로 설정하세요. 이 명령은 데이터 호출 1회를 사용합니다. UTF-8 저장 예시와 재시도·동기화 규칙은 다운로드 문서에 포함되어 있습니다.