NextPDF Connect — REST 전송

한눈에 보기

REST 전송은 RoadRunner HTTP 워커 풀 내부에서 bin/nextpdf-server를 실행합니다. 이 전송은 OpenAPI 3.1 문서로 기술되며, 헬스 체크가 아닌 모든 요청을 베어러 API 키로 인증하고, Pro 및 Enterprise 라우트를 설치된 등급에 따라 게이트합니다.

설치

composer require nextpdf/server
./vendor/bin/rr get-binary

개념 개요

각 요청은 핸들러에 도달하기 전에 PSR-15 미들웨어 파이프라인을 통과합니다. 이 과정에서 요청 ID 할당, 본문 크기 및 등급별 페이로드 제한, CORS, 인증, 기능 권한 부여, IP별 및 클라이언트별 속도 제한, 멱등성, 타임아웃을 거칩니다. 응답을 스스로 생성할 수 없는 PSR-15 미들웨어는 제공된 요청 핸들러에 위임합니다(PSR-15 §2.2 MiddlewareInterface::process, 절 psr_15_handlers#2.2.p14). 파이프라인이 전달하는 PSR-7 요청 객체는 불변입니다. 상태를 변경하는 호출은 기존 객체를 제자리에서 바꾸지 않고 새 인스턴스를 반환합니다(PSR-7 §3.2.1).

라우트 테이블은 부팅 시 구성되며 런타임 상태에 따라 달라집니다. 코어 라우트는 항상 등록되고, Pro 작업 라우트는 Pro 또는 Enterprise가 설치된 경우에만 등록되며, Enterprise 라우트는 Enterprise가 설치된 경우에만 등록됩니다. 세션 라우트는 세션이 활성화된 경우에만 등록됩니다.

API 표면

항상 등록되는 라우트

메서드	경로	인증
GET	/healthz	없음 (라이브니스)
GET	/readyz	없음 (레디니스)
POST	/api/v1/render	베어러
GET	/api/v1/capabilities	베어러
POST	/api/v1/jobs	베어러
GET	/api/v1/jobs/{id}	베어러
GET	/api/v1/jobs/{id}/result	베어러
DELETE	/api/v1/jobs/{id}	베어러
POST	/api/v1/extract-text · /merge · /split	베어러

헬스 프로브는 안전한 읽기 전용 엔드포인트입니다. 상태 변경을 일으키지 않으며, 이는 RFC 9110이 안전한 메서드에 대해 정의하는 속성입니다(RFC 9110 §9.2.1).

등급 게이트 라우트 (런타임 의존)

해당 패키지가 설치된 경우에만 등록됩니다:

• Pro 또는 Enterprise 설치됨: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise 설치됨: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

설치되지 않은 등급의 라우트로 보낸 요청은 라우팅되지 않습니다. 라우트가 요구하는 등급보다 낮은 등급의 키로 인증된 요청은 403으로 거부됩니다. 서명 기능이 노출되는 경우, Pro가 적용된 NextPDF Connect는 PAdES baseline-B(B-B) 서명만 제공합니다. 장기 검증 프로필은 이 전송의 표면에 포함되지 않습니다.

OpenAPI 계약

REST 표면은 패키지 내 openapi/nextpdf-connect.yaml에 정적 OpenAPI 3.1 문서로 제공됩니다. 보안 스킴은 Authorization 헤더에 담긴 베어러 API 키입니다(Bearer npk_live_{kid}_{secret}). 오류 응답은 RFC 7807 problem-details 문서이며, 조건마다 type URL을 가집니다.

OpenAPI 렌더링 — Scalar

문서 플랫폼 계획 §12에 따라, 통합 문서 사이트는 이 OpenAPI 문서를 Scalar(@scalar/api-reference)로 렌더링합니다. 이 문서는 REST 통합 페이지에 <ScalarApiReference src=…> 컴포넌트로 임베드됩니다. 신뢰의 원천은 패키지의 openapi/nextpdf-connect.yaml입니다. 사이트 빌드는 별도의 엔드포인트 레퍼런스를 수작업으로 유지하는 대신 이를 가져와 렌더링합니다. 런타임에 OpenAPI를 제공하는 엔드포인트는 서버에 포함되지 않습니다. 이 문서는 빌드 타임 아티팩트입니다.

코드 샘플 — 빠른 시작

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

코드 샘플 — 프로덕션

REST 및 gRPC 전송이 하나의 슈퍼바이저를 공유하도록 결합 프로필을 실행합니다:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
./vendor/bin/rr serve -c .rr.full.yaml

엣지 케이스 및 주의 사항

• 패키지가 없으면 등급 라우트는 404를 반환합니다. 해당 라우트가 등록되지 않으므로 라우터가 이를 매칭하지 않습니다. 이는 예상된 동작이며, 인증 실패가 아닙니다.

• 401 대 403. 401은 유효한 키가 없음을 의미합니다(그리고 응답은 WWW-Authenticate: Bearer 헤더를 포함하며, 이는 RFC 9110 §11.6.1을 따릅니다). 403은 유효한 키이지만 해당 등급이 그 작업에 대한 권한이 없음을 의미합니다.

• 세션은 기본적으로 꺼져 있습니다. /api/v1/sessions/... 라우트는 NEXTPDF_SESSIONS_ENABLED=true이고 도구를 사용할 수 있는 경우에만 존재합니다.

• 고위험 작업은 여전히 게이트됩니다. ApprovalRequired 도구를 구동하는 REST 호출은 MCP와 동일한 휴먼 인 더 루프 게이트를 거칩니다. /connect/hitl-risk-tiers/. 항목을 참조하십시오.

성능

각 RoadRunner 워커는 한 번에 하나의 요청을 처리합니다. 긴 동기 렌더링은 워커를 점유합니다. 느린 작업에는 비동기 작업 라우트를 사용해 워커가 해제되도록 합니다. 관측된 지연 시간에 맞춰 풀 크기를 조정합니다. /connect/production-usage/. 항목을 참조하십시오.

보안 참고 사항

REST 리스너 앞단에서 TLS를 종료합니다. 이는 설계상 평문 HTTP에 바인딩되며 업스트림 종료자를 전제로 합니다. 충분히 무작위인 npk_live_ 키로 인증하고, 키를 소스 관리 외부에 저장하며, 핫 리로딩 파일 키 저장소를 우선 사용합니다. /connect/security-and-operations/. 항목을 참조하십시오.

준수

주장	출처	reference_id
401은 반드시 WWW-Authenticate 챌린지를 포함해야 합니다	RFC 9110 §11.6.1
안전한 메서드는 읽기 전용입니다	RFC 9110 §9.2.1
PSR-7 요청은 불변입니다	PSR-7 §3.2.1
응답을 생성할 수 없는 미들웨어는 제공된 요청 핸들러에 위임합니다	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

상업적 컨텍스트

서명, 교정, 비교, 접근성, 최적화, 규정 준수 라우트는 nextpdf/premium이 설치된 경우에만 나타납니다. 인증 모델은 변경되지 않습니다. 키의 등급이 접근 권한을 결정합니다.

참고 항목

• /connect/quickstart/ — 실행 가능한 렌더링 요청
• /connect/security-and-operations/ — 인증 및 TLS 태세
• /connect/production-usage/ — 작업, 멱등성, 속도 제한
• /transports/mcp/ · /transports/grpc/ — 다른 전송
• /connect/tool-catalog/ — 라우트 집합이 도구 카탈로그에 매핑되는 방식