NextPDF Connect — REST-транспорт

Краткий обзор

REST-транспорт запускает bin/nextpdf-server в пуле рабочих процессов RoadRunner по HTTP. Документ OpenAPI 3.1 описывает доступную поверхность API. Транспорт аутентифицирует все запросы, кроме проверок состояния, с помощью токена-носителя — ключа API — и разграничивает маршруты Pro и Enterprise по установленному уровню.

Установка

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

Концептуальный обзор

Перед тем как попасть в обработчик, каждый запрос проходит через конвейер промежуточного ПО PHP Standard Recommendation 15 (PSR-15): присвоение идентификатора запроса, ограничения размера тела и полезной нагрузки по уровню, совместное использование ресурсов между источниками (CORS), аутентификация, авторизация возможностей, ограничение частоты запросов по IP и клиенту, идемпотентность и тайм-аут. Промежуточное ПО PSR-15, если не может сформировать ответ самостоятельно, делегирует обработку предоставленному обработчику запроса (PSR-15 §2.2 MiddlewareInterface::process, пункт psr_15_handlers#2.2.p14). Объекты запроса PHP Standard Recommendation 7 (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	токен-носитель

Проверки состояния — это безопасные конечные точки только для чтения. Они не изменяют состояние; это свойство безопасного метода определено в Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Маршруты с разграничением по уровням (зависят от среды выполнения)

NextPDF регистрирует эти маршруты только при установленном соответствующем пакете:

• Установлен Pro или Enterprise: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Установлен Enterprise: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Если уровень маршрута не установлен, маршрут не регистрируется и запрос не попадает в маршрутизацию. Если ключ действителен, но его уровень ниже уровня маршрута, запрос отклоняется с кодом 403. Когда доступно подписание, NextPDF Connect с Pro поддерживает только подписание по профилю baseline-B (B-B) усовершенствованных электронных подписей PDF (PAdES); профили долговременной проверки не входят в поверхность этого транспорта.

Контракт OpenAPI

Поверхность REST поставляется в пакете как статический документ OpenAPI 3.1 по пути openapi/nextpdf-connect.yaml. В ней используется схема безопасности для ключа API в виде токена-носителя в заголовке Authorization (Bearer npk_live_{kid}_{secret}). Ответы об ошибках используют документы problem-details по RFC 7807 с URL type для каждого условия.

Отрисовка 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 и инструменты доступны.

• Высокорисковые операции по-прежнему разграничиваются. REST-вызов, который задействует инструмент ApprovalRequired, проходит через тот же шлюз с участием человека, что и протокол Model Context Protocol (MCP). См. /connect/hitl-risk-tiers/.

Производительность

Каждый рабочий процесс RoadRunner обрабатывает один запрос за раз. Длительные синхронные операции отрисовки занимают рабочий процесс. Используйте асинхронные маршруты заданий для медленной работы, чтобы освобождать рабочие процессы. Подбирайте размер пула с учётом наблюдаемой задержки; см. /connect/production-usage/.

Замечания по безопасности

Завершайте защиту транспортного уровня (TLS) перед REST-слушателем. По умолчанию слушатель привязан к HTTP без TLS и рассчитывает на вышестоящий терминатор. Для аутентификации используйте достаточно случайный ключ 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/ — как набор маршрутов соотносится с каталогом инструментов