REST API

개발者优先

REST API 는 Glossia 의 핵심입니다. 대시보드, CLI, 그리고 MCP 서버 는 모두 동일한 엔드포인트를 사용합니다. 새로운 기능을 추가할 때, 그것은 먼저 API 에 구현되어 다른 모든 곳에서 이를 노출합니다.

이는 UI 에 의해 제한될 일이 없습니다. CI/CD 통합이나 커스터마이징 대시보드까지 여행할 수 있는 모든 워크플로우를 같은 안정적이고 문서화된 인터페이스 위에서 구축할 수 있습니다.

인증

Glossia 는 모든 API 인증에 OAuth 2.1 과 PKCE 를 사용합니다. 이 플로우 는 직접 클라이언트와 제 3 자 클라이언트를 모두 지원합니다. 전체 설명을 보려면 인증 및 권한 부여 문서 를 참조하세요.

동적 클라이언트 등록 -- 클라이언트는 리디렉션 URI 와 권한 유형과 함께 /oauth/register에서 프로그램 방식으로 등록됩니다. 수동 승인 단계를 밟지 않아도 되며, 클릭해야 할 포털이 없습니다.

PKCE 와 함께 사용하는 인증 코드 -- 사용자가 브라우저 기반 동의를 통해 클라이언트를 승인합니다. PKCE 확장은 모든 공개 클라이언트들이 보안 토큰을 안전하게 유지하도록 보장합니다.

토큰 라이프사이클 -- 액세스 토큰을 표준 OAuth 엔드포인트를 통해 교환하고, 쿼리, 마지막으로 취소할 수 있습니다. 토큰 엔드포인트의 속도 제한은 brute force 를 방지합니다.

권한 부여

접근 제어는 두レイ어를 사용합니다. 인증 문서 는 스코프, 역할, 그리고 전체 권한 매트릭스를 자세히 다룹니다.

스코프는 토큰이 접근할 수 있는 리소스 범주 정의합니다. voice:read를 가진 토큰은 VOICE 설정을 읽을 수는 있지만 수정할 수는 없습니다. 스코프는 resource:action 패턴에 따릅니다: account:read는 디자인 관리, organization:write는 뷰어 관리, glossary:admin는 관리등, 이어집니다.

정책은 사용자와 특정 리소스 간의 관계를 확인합니다. 올바른 스코프가 있는 유효한 토큰도 사용자가 속하지 않은 조직에 접근할 수 없습니다. 모든 요청은 두 레이어 모두와 비교하여 확인됩니다.

페이징, 필터링, 정렬

모든 목록 엔드포인트는 일관된 메타데이터로 파지된 결과를 반환합니다.

모든 응답에는 total_count, total_pages, current_page, page_size, has_next_page?, 및 has_previous_page?이 포함되어 있으므로 클라이언트는 추측 없이 페이지네이션 컨트롤을 구성할 수 있습니다.

filters[field]=value 와 같은 인덱스 필드를 필터링하세요. order_by[] 이와 같은 인덱스 필드에서 오름차순, 내림차순으로 정렬하세요. 인터페이스는 모든 리소스에서 동일합니다.

OpenAPI 와 인터랙티브 문서

완전한 OpenAPI 3.1 규정은 /api/openapi.json에서 사용할 수 있습니다. 인터랙티브 API 참조 는 Scalar 기반으로 작동하며, 엔드포인트를 탐색하고 스키마를 검사하며 브라우저에서 직접 테스트 요청을 만들 수 있습니다.

어떤 언어의 클라이언트 라이브러리를으로도 생성할 수 있습니다. 계약은 버전 관리되고 안정적이며, 새로운 기능을 구현할 때에도 기존 인테그레이션이 손상되지 않습니다.