Connect REST API 참조

한눈에 보기

NextPDF Connect는 도구 레지스트리를 REST 전송을 통해 HTTP로 노출하며, 이는 OpenAPI 3.1 계약으로 기술됩니다. 이 페이지는 해당 인터페이스에 대한 참조입니다. 기본 URL, 인증 방법, 작업 그룹, 오류 모델을 다룹니다. 전체 기계 판독 가능 사양이 게시되어 있으므로, 무엇도 손으로 복사하지 않고 대화형 탐색기, 클라이언트 생성기 또는 요청 클라이언트에 로드할 수 있습니다.

전송 방식과 무관한 도구 카탈로그(REST뿐 아니라 Model Context Protocol 및 gRPC를 통한 동일한 작업)는 Connect API 참조를 참조하세요. RoadRunner 파이프라인, 배포 및 인증 설정은 REST 전송 가이드를 참조하세요.

기본 URL 및 인증

REST 전송은 배포에 맞게 구성된 호스트와 포트에서 수신 대기합니다. 로컬 실행에서는 http://localhost:8080이며, 프로덕션에서는 워커 풀 앞단의 주소입니다.

인증 방식은 베어러 토큰입니다. 티어 제한이 적용되는 라우트에 대한 모든 요청에서는 Authorization 헤더로 API 키를 전송하세요.

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

읽기 전용 라이브니스 및 레디니스 프로브에는 토큰이 필요하지 않습니다.

작업

사용 가능 여부는 티어에 따라 제한됩니다. 오픈 소스 코어는 문서, 렌더링, 세션 및 작업(job) 관련 작업을 제공합니다. 서명, 양식 작성, 수정 마스킹(redaction), 비교, 접근성 검사, 최적화에는 서버와 함께 설치된 상용 에디션이 필요합니다. 특정 배포에서 사용할 수 있는 권위 있는 작업 집합은 capabilities 엔드포인트에서 반환됩니다. 고정된 목록을 가정하지 말고 해당 엔드포인트를 조회하세요.

상태 및 수명 주기

메서드	경로	용도
GET	`/healthz`	라이브니스 프로브. 인증 없음.
GET	`/readyz`	레디니스 프로브(종속성 및 워커 풀 준비 완료). 인증 없음.
GET	`/api/v1/capabilities`	이 배포가 실제로 노출하는 도구와 티어입니다. 가장 먼저 조회하세요.

렌더링 및 문서

메서드	경로	용도
POST	`/api/v1/render`	정렬된 작업 목록에서 문서를 렌더링하고 PDF를 반환합니다.
POST	`/api/v1/extract-text`	PDF에서 텍스트 콘텐츠를 추출합니다.
POST	`/api/v1/merge`	여러 PDF 입력을 하나의 문서로 병합합니다.
POST	`/api/v1/split`	PDF를 여러 문서로 분할합니다.

비동기 작업

메서드	경로	용도
POST	`/api/v1/jobs`	장기 실행 작업을 작업(job)으로 제출합니다.
GET	`/api/v1/jobs/{id}`	작업 상태를 폴링합니다.
GET	`/api/v1/jobs/{id}/result`	완료된 작업 결과를 검색합니다.

세션

세션은 여러 호출 동안 문서를 열린 상태로 유지하므로, 문서를 점진적으로 구성하고 마지막에 한 번 렌더링할 수 있습니다.

메서드	경로	용도
POST	`/api/v1/sessions`	세션을 엽니다.
GET / DELETE	`/api/v1/sessions/{sessionId}`	세션을 검사하거나 닫습니다.
POST	`/api/v1/sessions/{sessionId}/pages`	페이지를 추가합니다.
POST	`/api/v1/sessions/{sessionId}/text`	텍스트를 추가합니다.
POST	`/api/v1/sessions/{sessionId}/images`	이미지를 추가합니다.
POST	`/api/v1/sessions/{sessionId}/tables`	표를 추가합니다.
POST	`/api/v1/sessions/{sessionId}/html`	렌더링된 HTML을 추가합니다.
POST	`/api/v1/sessions/{sessionId}/font`	활성 글꼴을 설정합니다.
POST	`/api/v1/sessions/{sessionId}/render`	세션 문서를 렌더링합니다.

상용 에디션 작업

이 라우트들은 해당 상용 에디션이 설치된 경우에만 등록됩니다. 일부에는 휴먼-인-더-루프 확인 흐름을 통한 승인 게이트가 적용됩니다. 위험 티어를 참조하세요.

메서드	경로	용도
POST	`/api/v1/sign`	디지털 서명을 적용합니다.
POST	`/api/v1/fill-form`	대화형 양식을 작성합니다.
POST	`/api/v1/redact`	콘텐츠를 수정 마스킹(redaction)합니다.
POST	`/api/v1/compare`	PDF 문서 두 개를 비교합니다.
POST	`/api/v1/check-accessibility`	구조적 접근성 검사를 실행합니다.
POST	`/api/v1/optimize`	문서를 최적화하고 크기를 줄입니다.

오류 모델

REST 전송은 RFC 9110에 정의된 의미 체계에 따라 HTTP 상태 코드를 사용합니다. 2xx는 성공을 나타냅니다. 4xx는 호출자가 수정해야 하는 요청에 사용되며(400 잘못된 형식의 본문, 401 누락되었거나 유효하지 않은 토큰, 403 티어 또는 승인 거부, 404 알 수 없는 라우트 또는 작업, 409 멱등성 충돌, 422 엔진이 처리할 수 없는 올바른 형식의 요청), 5xx는 서버 측 실패에 사용됩니다. 401 응답은 WWW-Authenticate 챌린지를 전달합니다.

오류 본문은 RFC 9457(Problem Details for HTTP APIs)에 따른 application/problem+json 문서입니다. 안정적인 type, 짧은 title, 숫자 status, 사람이 읽을 수 있는 detail로 구성됩니다. 매칭에는 type을 사용하고, detail 문자열은 사용하지 마세요. 규범적 정의는 RFC 9110(HTTP Semantics) 및 RFC 9457도 참조하세요.

상태를 변경하는 요청이 재시도되어도 한 번만 처리되도록 Idempotency-Key 헤더와 함께 제출하세요.

기계 판독 가능 사양

전체 계약은 정적 OpenAPI 3.1 문서로 게시됩니다:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

REST 인터페이스의 단일 진실 공급원으로 이를 사용하세요:

이 계약에서 생성되고 브라우저 내에서 자체 호스팅되는 Scalar 참조인 대화형 API 탐색기를 열어, 각 작업을 요청 및 응답 스키마와 함께 읽고 시험해 보세요.
Postman 또는 Insomnia와 같은 요청 클라이언트로 가져오세요.
OpenAPI 생성기를 사용해 사용하는 언어에 맞는 타입 지정 클라이언트를 생성하세요.

이 문서는 패키지에 버전이 고정된 정적 계약입니다. 라이브 엔드포인트로 제공되는 것이 아니므로, 배포 전반에 걸쳐 안정적으로 유지됩니다.