Optifora API의 동작 방식
이 페이지는 API의 구조를 설명합니다. 신원을 어떻게 증명하는지, 버전이 어떻게 올라가는지, 요청이 지켜야 할 한도는 무엇인지, 오류는 어떤 모습인지, 그리고 외부와 데이터를 어떻게 주고받는지를 다룹니다.
제품은 개발 중이며 API 영역도 계속 보완되고 있습니다. 엔드포인트에 대한 참조 문서는 별도로 공개될 예정입니다. 이 페이지에는 주소나 예제 호출이 없으며 동작 원리만 설명합니다.
인증
모든 요청은 사람 또는 등록된 애플리케이션 중 하나에 속합니다. 신원 없이 보호된 엔드포인트에 도달한 요청은 인증되지 않음으로 반환됩니다.
- Bearer 토큰액세스 토큰은 요청의 인증 헤더에 담겨 전달됩니다. 토큰은 서명되어 있으며, 해당 요청이 누구의 것인지만 나타냅니다.
- 짧은 유효 기간액세스 토큰은 분 단위로 정해진 시간이 지나면 만료됩니다. 유효 시간은 배포 설정값이며 기본값은 30분입니다.
- 갱신과 순환세션은 갱신 토큰으로 연장되며, 연장할 때마다 새로운 토큰 쌍이 발급됩니다. 이미 사용된 갱신 토큰이 다시 제시되면 해당 사용자의 모든 세션이 무효화됩니다.
- 권한은 토큰에 담기지 않습니다토큰은 신원만 담고 있으며, 사용자가 무엇을 볼 수 있는지는 요청마다 데이터베이스에 확인합니다. 따라서 회수된 권한은 가지고 있는 토큰이 만료되기 전에 곧바로 효력을 잃습니다.
- 연동 사업자 키등록된 애플리케이션은 자체 키로 연결합니다. 키의 원문 값은 생성 시점에 한 번만 표시되며, 저장되는 것은 그 해시값과 키를 식별하기 위한 비밀이 아닌 접두어입니다.
- 접근 권한은 조직이 부여합니다애플리케이션이 아무리 널리 쓰이더라도 조직이 기록한 승인이 없으면 단 한 건의 데이터도 볼 수 없습니다. 승인에는 날짜와 범위가 있으며 언제든 철회할 수 있습니다.
버전 관리
- 버전은 경로에 담깁니다엔드포인트는 버전 접두어 뒤에 공개됩니다. 현재 제공되는 것은 버전 1입니다.
- 호환되지 않는 변경은 새 경로를 엽니다기존 엔드포인트의 규약은 그 자리에서 깨뜨리지 않습니다. 호환되지 않는 변경은 새로운 버전 경로로 공개하고 기존 경로는 계속 동작합니다.
- 문서가 자신의 버전을 밝힙니다참조 문서에는 생성된 버전 번호가 표시됩니다. 지금 어떤 버전을 보고 있는지는 문서 자체가 알려줍니다.
운영 환경과 한도
참조 문서에는 운영 환경과 로컬 개발 환경 두 가지가 정의되어 있습니다. 루트 주소는 연동 사업자에게 키와 함께 전달되며 이 페이지에는 공개하지 않습니다.
- 생존 여부와 준비 여부를 따로 측정합니다한 엔드포인트는 프로세스가 살아 있는지를 알려주고, 두 번째 엔드포인트는 데이터베이스에 실제 질의를 보내 연결 가능 여부를 확인합니다. 트래픽을 보낼지 결정하는 것은 두 번째 엔드포인트뿐입니다.
- 브라우저 출처는 목록으로 제한됩니다교차 출처 요청은 사전에 등록된 출처에서만 허용됩니다. 목록이 비어 있는 동안에는 브라우저의 교차 출처 요청이 거부됩니다.
- 본문 크기 제한요청 본문은 5메가바이트를 넘을 수 없습니다. 대용량 데이터는 단일 요청이 아니라 자체 상태 기록을 가지는 일괄 전송 작업으로 처리됩니다.
- 비밀 정보는 로그에 기록하지 않습니다서버 로그에는 인증 헤더, 쿠키, 비밀번호, 주민등록번호에 해당하는 개인 식별번호가 기록되지 않습니다.
호출 한도
한도는 주소별, 분 단위로 적용됩니다. 기본값은 분당 120회이며 배포 시 설정합니다. 남은 횟수는 모든 응답의 헤더에 표시됩니다.
| 응답 헤더 | 표시 내용 |
|---|---|
| x-ratelimit-limit | 해당 구간 안에서 허용되는 총 횟수입니다. |
| x-ratelimit-remaining | 현재 구간에서 남은 횟수입니다. |
| x-ratelimit-reset | 허용량이 초기화될 때까지 남은 초입니다. |
| retry-after | 재시도까지 기다려야 하는 초입니다. 요청이 거부된 응답에만 포함됩니다. |
한도를 넘으면 요청은 거부되고, 응답에 몇 초를 기다려야 하는지가 표시됩니다. 재시도는 즉시가 아니라 그 시간이 지난 뒤에 합니다.
오류 형식
모든 오류는 동일한 형태로 반환됩니다. 기계가 분기 처리할 짧은 코드 필드와 사람이 읽을 설명 필드로 구성됩니다.
- error클라이언트가 분기 처리에 사용하는 짧은 코드입니다.
- message무슨 일이 일어났는지에 대한 설명입니다.
| 상태 | 코드 필드 | 의미 |
|---|---|---|
| 400 | Bad Request | 요청이 스키마와 일치하지 않습니다. 설명에 누락되었거나 잘못된 필드 이름이 표시됩니다. |
| 401 | unauthenticated | 유효한 신원이 없습니다. 토큰이 전달되지 않았거나, 만료되었거나, 검증에 실패했습니다. |
| 404 | Not Found | 해당 엔드포인트가 없거나 해당 레코드가 없습니다. |
| 429 | Too Many Requests | 호출 한도를 초과했습니다. 응답에 얼마나 기다려야 하는지가 표시됩니다. |
| 5xx | internal_error | 예기치 못한 오류입니다. 상세 내용은 클라이언트에 전달되지 않고 서버 로그에 기록됩니다. |
페이지 처리
목록을 반환하는 엔드포인트는 모두 같은 두 개의 매개변수를 받고 같은 카운터를 반환합니다. 따라서 페이지 처리 코드를 엔드포인트마다 다시 작성할 필요가 없습니다.
- limit한 페이지에 담을 레코드 수입니다. 최소 1개, 최대 200개이며 지정하지 않으면 50개입니다.
- offset건너뛸 레코드 수입니다. 0부터 시작합니다.
- total필터 조건에 해당하는 전체 레코드 수입니다.
- count이 응답이 실제로 담고 있는 레코드 수입니다.
응답에는 사용된 limit과 offset 값도 함께 반환됩니다. 클라이언트는 자신의 위치를 추측하지 않고 응답에서 읽습니다.
데이터 교환과 웹훅
교환 방식은 별도의 제품이 아니라 설정값입니다. 등록된 모든 애플리케이션은 자신이 동작하는 방식을 자체 등록 정보에 담고 있습니다.
| 방식 | 의미 |
|---|---|
| 단방향 — 송신 | Optifora가 데이터를 제공하고, 상대 시스템이 이를 읽거나 이벤트를 구독합니다. |
| 단방향 — 수신 | 상대 시스템이 데이터를 전송하고, Optifora가 이를 검증한 뒤 기록합니다. |
| 양방향 | 양쪽 모두 데이터를 기록하며, 충돌 처리 규칙은 사전에 정의합니다. |
| 핸드셰이크 | 모든 전송은 하나의 세션으로 진행됩니다. 제안, 검증, 승인, 전송, 수신 확인 순서이며 수신 확인 기록은 양쪽에 남습니다. |
- 이벤트는 외부로 전송됩니다웹훅은 등록된 애플리케이션이 지정한 콜백 주소로 이벤트를 전송합니다. 전달되지 못한 이벤트는 대기열에 남아 재전송되며, 조용히 버려지는 일은 없습니다.
- 같은 요청이 두 번 기록되지 않습니다쓰기 요청에는 멱등성 키가 포함됩니다. 같은 키를 가진 두 번째 요청은 새로운 레코드를 만들지 않습니다.
- 모든 호출이 기록됩니다누가, 언제, 어떤 범위로, 어떤 결과로 호출했는지가 모두 기록됩니다. 이 기록 하나로 장애 분석과 누가 이 데이터를 조회했는지에 대한 질문 모두에 답할 수 있습니다.
- 우리 애플리케이션도 같은 문을 씁니다특권적인 별도 경로는 존재하지 않습니다. 우리 자신의 연동이 곧 외부 개발자가 만나는 인터페이스에 대한 증명입니다.
교환 계층의 데이터 모델은 이미 갖추어져 있으나 엔드포인트는 아직 공개되지 않았습니다. 공개되면 이 항목에서 참조 문서의 해당 항목으로 연결됩니다.
참조 문서
참조 문서는 사람이 직접 작성하지 않고 엔드포인트 스키마에서 생성됩니다. 각 엔드포인트가 스키마를 제공하면 문서가 자동으로 채워지므로, 문서와 실제 동작이 어긋날 수 없습니다.
- 현재: 준비 중스키마는 모듈 단위로 정리되고 있습니다. 문서가 공개되기 전에 모든 엔드포인트의 요청과 응답이 문서에 담기게 됩니다.
- 두 가지 형식으로 공개됩니다기계가 읽을 수 있는 OpenAPI 문서와, 같은 문서에서 생성되어 브라우저에서 볼 수 있는 참조 페이지입니다.
- 접근 권한은 단계별입니다개요는 누구에게나 공개됩니다. 전체 참조 문서는 등록된 연동 사업자에게 발급되는 문서 열람 토큰 뒤에 놓일 수 있습니다. 운영 키와 콜백 주소는 애초에 문서의 영역이 아니며 애플리케이션 등록 정보에 속합니다.
- 주소 표준두 개의 참조 문서가 공개되며 주소는 고정되어 있습니다. client-api.optifora.com/docs는 공개되어 있고, admin-api.optifora.com/docs는 인가가 필요하며 외부에는 닫혀 있습니다. 현재는 둘 다 운영 중이 아니며, 운영이 시작되면 이 항목에 링크가 추가됩니다.
연동 계획이 이미 확정되어 있다면 문의 페이지를 통해 연락해 주십시오. API가 공개될 때 가장 먼저 안내드립니다.