API 전용 주소와 환경
Sursa API에는 사람들이 브라우저로 Sursa를 열 때 쓰는 주소와 별개인 전용 주소가 있어요. 모든 경로는 /v1로
시작해요.
| Sursa가 실행되는 곳 | API 전용 주소 | 이 포털 |
|---|---|---|
| Sursa 클라우드 | https://api.sursa.com | https://developers.sursa.com |
| 자체 설치 환경 | 관리자가 설정한 https://api.<your domain> | API 전용 주소의 /developers/ |
| 별도의 API 전용 주소가 없는 자체 설치 환경 | 설치 환경의 메인 주소 | 메인 주소의 /developers/ |
API 전용 주소는 API만 제공해요. 로그인 페이지, 쿠키, 웹 화면이 없어요. 모든 요청은 API 키나 OAuth 액세스 토큰으로 인증해요. 이 주소는 로드 밸런서 뒤에 있는 여러 서버가 처리할 수 있으며, 연동 시스템은 서버가 몇 대인지 알 필요가 없어요.
메인 주소(예: https://app.sursa.com/v1)로 API를 호출하는 연동도 계속 동작해요. 몇 가지 차이점과 단계별 이전 방법은
API 전용 주소로 옮기기를 참고하세요.
기본 URL
모든 요청을 설정에 둔 기본 URL 하나로 만들면 같은 코드가 어떤 환경에서든 동작해요.
export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"
HTTPS만 사용하고, 직접 보내는 요청의 로그에 키가 남지 않게 하세요.
버전과 명세
GET /v1/health는 그 주소가 동작하는지 알려 주고, 그 주소를 제공하는 Sursa의 버전을
반환해요. 키 없이도 응답하므로 모니터링에 쓸 수 있어요.
curl https://api.sursa.com/v1/health{"ok": true, "version": "v1.4.0"}
이 값은 API의 버전이 아니라 Sursa 릴리스의 버전이에요. API의 버전은 명세의 info.version이에요. API의 OpenAPI 3.1
명세는 같은 주소에 인증 없이 공개되어 있어요.
| 경로 | 내용 |
|---|---|
GET /openapi.json | 공개 명세. servers 항목에 이 주소가 들어 있어요. |
GET /v1/openapi-public.json | 같은 명세. ETag와 If-None-Match를 지원해요. |
명세로 클라이언트를 생성하거나, Postman 같은 도구로 API를 가져오거나, 연동이 예상한 버전의 오퍼레이션만 쓰는지 CI에서 확인할 수 있어요. 이 포털의 API 레퍼런스도 같은 파일로 만들어요.
테스트
Sursa에는 별도의 테스트 모드가 없어요. 키로 보낸 모든 요청은 그 조직의 실제 데이터에 적용돼요. 안전하게 개발하고 테스트하려면 다음과 같이 하세요.
- 개발용으로, 작업에 필요한 가장 좁은 역할과 스코프의 키를 따로 만드세요.
- 팀만 볼 수 있는 전용 컬렉션(예:
sandbox)에 쓰고, 작업이 끝나면 삭제하세요. - 회사에 테스트용 Sursa 조직이나 설치 환경이 따로 있다면 기본 URL과 키를 그쪽으로 바꾸세요. 코드의 다른 부분은 바뀌지 않아요.
- 처음부터 재시도를 안전하게 만드세요. 모든
POST와PATCH요청에 Idempotency-Key를 보내세요.
API 레퍼런스의 각 엔드포인트 페이지에 있는 사용해 보기 콘솔은 붙여 넣은 키로 실제 요청을 보내요. 키는 브라우저 탭의 메모리에만 보관되며 API 전용 주소로만 전송돼요.
네트워크 요구 사항
- 서버에서 API 전용 주소로 나가는 HTTPS(443 포트) 연결.
- 네트워크가 허용한다면 방화벽 규칙에 고정 IP 주소 대신 호스트 이름을 허용하세요. 처리 용량이 늘어나면 주소 뒤의 서버가 바뀔 수 있어요.
- 브라우저 애플리케이션은 API를 직접 호출할 수 있어요. 응답은 쿠키 없이 모든 오리진을
허용해요(
Access-Control-Allow-Origin: *). 브라우저에서 쓰는 키는 그 브라우저의 사용자에게 보인다는 점을 기억하세요.