API 전용 주소로 옮기기

이전 연동은 사람들이 브라우저로 여는 Sursa의 메인 주소(예: https://app.sursa.com/v1/…)로 API를 호출해요. 이제 API에는 별도의 주소도 있어요. 클라우드에서는 https://api.sursa.com, 자체 설치 환경에서는 https://api.<your domain>이에요. 이 주소는 연동을 위해 만들어졌어요. 로드 밸런서 뒤에서 수평으로 확장되며 API만 제공해요.

옮기지 않아도 돼요. 메인 주소는 기존 연동을 위해 종료일이나 리디렉션 없이 계속 /v1을 제공해요. API 전용 주소의 장점이 필요할 때 편한 시점에 옮기고, 새 연동에는 모두 API 전용 주소를 쓰세요.

그대로인 것

경로, 파라미터, 필드, 오류 코드, 이벤트. GET /v1/cards는 두 주소에서 같은 요청이에요.
API 키. 같은 kb_ 키와 kbsrc_ 키가 같은 역할, 스코프, 데이터 프로필로 두 주소에서 모두 동작해요.
멱등성 키, 호출 한도, 할당량. 두 주소로 보낸 요청은 조직의 같은 할당량에 계산돼요.
웹훅. 전송, 서명, 시크릿은 호출하는 주소와 관계없어요.
응답의 링크. 어느 주소를 호출하든 오류의 doc_url은 이 포털을, 목록 페이지의 Link 헤더는 API 전용 주소를 가리켜요.

API 전용 주소에서 달라지는 것

메인 주소	API 전용 주소
내부용을 포함한 웹 애플리케이션의 모든 엔드포인트	공개 API 레퍼런스의 엔드포인트만. 그 밖의 경로는 `404` 상태와 `api.not_found` 코드로 응답해요.
`X-API-Key`나 `Authorization` 헤더의 키, 또는 브라우저 세션 쿠키	키나 OAuth 액세스 토큰만 받아요. 가급적 `Authorization: Bearer`로 보내세요. 쿠키는 무시돼요.
`GET /auth/me`	`GET /v1/me`. `/auth/` 아래의 경로는 제공하지 않아요.
쿠키를 이용한 “View as”(다른 사용자로 보기) 모드	`admin` 역할의 키에서 쓰는 `X-View-As` 헤더.
서버 한 대 또는 고정된 서버 묶음	로드 밸런서 뒤의 여러 서버.

마지막 행은 POST /v1/chat의 스트리밍 답변 한 가지 경우에만 중요해요. 끊긴 스트림은 답변을 작성하는 서버에서만 Last-Event-ID부터 이어져요. 연동이 스트림을 재개한다면 질문마다 request_id를 지정하세요. 그러면 다른 서버로 재시도해도 두 번째 답변이 아니라 저장된 답변을 받아요. 끊긴 스트림 재개하기를 참고하세요.

옮기기 전에

모든 호출이 공개 API인지 확인하세요. 연동이 호출하는 경로를 나열하고 각각을 API 레퍼런스에서 찾아보거나, 새 주소의 명세와 비교하세요.

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

공개 레퍼런스에 없는 경로는 웹 애플리케이션에 속해요. 메인 주소에서는 계속 동작하지만 API 전용 주소에서는 제공하지 않으며, 그 형태도 공개적으로 보장하지 않아요. 공개 엔드포인트로 바꾸거나, 연동의 그 부분은 메인 주소에 남겨 두고 필요한 기능을 Sursa 연락 창구에 알려 주세요.

인증 방식을 확인하세요. 연동이 사용자의 비밀번호와 세션 쿠키로 로그인한다면 먼저 API 키로 바꾸세요. X-API-Key를 보낸다면 Authorization: Bearer로 바꾸는 것을 권장하지만 필수는 아니에요.

네트워크를 확인하세요. 방화벽과 프록시에서 새 호스트 이름으로 나가는 HTTPS를 허용하세요.

단계별로 옮기기

기본 URL을 설정으로 분리하세요. 이미 연동의 설정 항목이라면 이 단계는 건너뛰세요.

새 주소를 시험하세요. 읽기 요청을 보내 보세요.

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

테스트 스위트를 실행하세요. 테스트 키와 테스트 컬렉션을 써서 새 주소로 연동의 테스트를 돌려요.
트래픽 일부를 전환하세요. 예를 들어 워커 하나나 환경 하나를 전환하고, 로그에서 404 api.not_found, 401, 5xx를 지켜보세요. 모든 응답에는 X-Request-Id가 있으니 로그와 함께 보관하세요.
나머지를 전환하세요. 몇 초 만에 되돌릴 수 있도록 이전 기본 URL을 한동안 설정에 남겨 두세요.

옮긴 뒤 확인할 것

새 주소의 GET /v1/health가 이전 주소와 같은 version을 반환해요.
응답에 RateLimit 헤더가 있어요. 연동이 X-RateLimit-* 헤더로 속도를 조절한다면 그대로 써도 돼요. 두 헤더 묶음이 모두 전송돼요. 호출 한도와 할당량을 참고하세요.
연동이 브라우저에서 실행된다면 CORS를 위한 자체 프록시가 더 이상 필요 없어요. API 전용 주소는 쿠키 없이 모든 오리진의 요청을 허용해요.