REST API

개발자 우선

REST API 는 Glossia 의 핵심입니다. 대시보드, CLI, 그리고 MCP 서버 모든 것이 동일한 엔드포인트를 소비합니다. 기능을 추가하면 API 에 먼저 구현되어 이후 다른 모든 곳에서 사용 가능합니다.

이는 UI 에 제한받지 않는다는 뜻입니다. 상상할 수 있는 워크플로우, CI/CD 통합부터 커스텀 대시보드까지 동일한 견고하고 문서화된 인터페이스 위에 구축할 수 있습니다.

인증

Glossia 는 모든 API 인증에 OAuth 2.1 및 PKCE 를 사용합니다. 이 프로세스는 제 1 자 및 제 3 자 클라이언트를 모두 지원합니다. 자세한 내용은 인증 및 권한 부여 문서 전체 가이드를 보려면.

동적 클라이언트 등록 -- 클라이언트는 프로그램 방식으로 등록됩니다. /oauth/register 리디렉션 URI 및 권한 유형 을 포함합니다. 수동 승인 단계가 없으며, 통과해야 할 포털 클릭도 없습니다.

PKCE 와 Authorization Code -- 사용자는 브라우저 기반의 동의 화면 을 통해 클라이언트를 승인합니다. PKCE 확장은 비밀을 저장할 수 없는 공개 클라이언트에서도 토큰 안전성을 보장합니다.

토큰 수명 주기 -- 액세스 토큰은 표준 OAuth 엔드포인트 를 통해 교환, 검토 및 철회할 수 있습니다. 토큰 엔드포인트 의 속도 제한 은 무차별 공격 을 방지합니다.

인가

접근 제어는 두 가지 계층을 사용합니다. 해당 인증 문서 범위, 역할, 및 전체 권한 행렬을 자세히 다룹니다.

범위 토큰이 접근 가능한 리소스의 범주를 정의합니다. 해당 토큰이 voice:read 음성 설정을 읽을 수는 있지만 수정할 수는 없습니다. 범위는 다음 resource:action 패턴: account:read이전에 재조립된 문서는 검증에서 실패했습니다: Markdown 텍스트 리터럴 복원에서 잘못된 JSON 이 반환되었습니다. organization:write다시 조립된 문서는 이전에 유효성 검사를 실패했습니다: 마크다운 텍스트 리터럴 복구는 길이가 일치하는 JSON 문자열 배열을 반환해야 합니다. 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 를 기반으로 하며 브라우저에서 직접 엔드포인트를 탐색하고 스키마를 검사하며 테스트 요청을 생성할 수 있습니다.

언어에 관계없이 클라이언트 라이브러리를 명세에서 생성할 수 있습니다. 계약은 버전 관리되어 안정적이므로 새로운 기능이 출시되어도 통합이 손상되지 않습니다.