NextPDF Connect — transporte REST

Visão geral

O transporte Representational State Transfer (REST) executa o bin/nextpdf-server em um pool de workers Hypertext Transfer Protocol (HTTP) do RoadRunner. A superfície é definida por um documento OpenAPI 3.1. O transporte autentica toda requisição que não seja de health com uma application programming interface (API) key bearer e habilita as rotas Pro e Enterprise conforme o tier instalado.

Instalação

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

Visão conceitual

Cada requisição passa por um pipeline de middleware PHP Standard Recommendation 15 (PSR-15) antes de chegar a um handler: atribuição de request-id, limites de tamanho do body e de payload por tier, Cross-Origin Resource Sharing (CORS), autenticação, autorização de capacidades, rate limiting por IP e por cliente, idempotência e timeout. Um middleware PSR-15 que não consegue produzir a resposta por conta própria delega ao request handler fornecido (PSR-15 §2.2 MiddlewareInterface::process, cláusula psr_15_handlers#2.2.p14). Os objetos de requisição PHP Standard Recommendation 7 (PSR-7) no pipeline são imutáveis: uma chamada que altera o estado retorna uma nova instância, em vez de modificar a original (PSR-7 §3.2.1).

A tabela de rotas é construída no boot e depende do runtime. As rotas Core são sempre registradas. As rotas de operação Pro só são registradas quando Pro ou Enterprise está instalado. As rotas Enterprise só são registradas quando Enterprise está instalado. As rotas de sessão só são registradas quando as sessões estão habilitadas.

Superfície da API

Rotas sempre registradas

Método	Caminho	Auth
GET	/healthz	nenhuma (liveness)
GET	/readyz	nenhuma (readiness)
POST	/api/v1/render	bearer
GET	/api/v1/capabilities	bearer
POST	/api/v1/jobs	bearer
GET	/api/v1/jobs/{id}	bearer
GET	/api/v1/jobs/{id}/result	bearer
DELETE	/api/v1/jobs/{id}	bearer
POST	/api/v1/extract-text · /merge · /split	bearer

As probes de health são endpoints seguros e somente leitura. Elas não causam nenhuma mudança de estado, que é a propriedade de um método seguro definida pelo Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Rotas controladas por tier (dependentes do runtime)

O NextPDF registra estas rotas apenas quando o pacote correspondente está instalado:

• Pro ou Enterprise instalado: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise instalado: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Se o tier da rota não estiver instalado, a rota não é registrada e a requisição não é roteada. Se a chave for válida, mas o tier da chave for inferior ao tier da rota, a requisição é rejeitada com 403. Nas rotas em que assinatura está exposta, o NextPDF Connect com Pro fornece apenas assinatura PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B); os perfis de validação de longo prazo não fazem parte da superfície deste transporte.

Contrato OpenAPI

A superfície REST é distribuída como um documento OpenAPI 3.1 estático em openapi/nextpdf-connect.yaml no pacote. Ele usa um esquema de segurança de API key bearer no header Authorization (Bearer npk_live_{kid}_{secret}). As respostas de erro usam documentos problem-details do RFC 7807 com uma URL type para cada condição.

Renderização do OpenAPI — Scalar

Conforme o plano da plataforma de documentação §12, o site agregado de documentação renderiza este documento OpenAPI com Scalar (@scalar/api-reference). A página de integração REST o incorpora como um componente <ScalarApiReference src=…>. O openapi/nextpdf-connect.yaml do pacote continua sendo a fonte da verdade. O build do site busca e renderiza esse arquivo, em vez de manter manualmente uma referência paralela de endpoints. Nenhum endpoint de runtime que sirva o documento OpenAPI faz parte do servidor; o documento é um artefato de build-time.

Exemplo de código — Início rápido

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

Exemplo de código — Produção

Use o profile combinado para que os transportes REST e gRPC compartilhem um único supervisor:

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

Casos de borda e pegadinhas

• Uma rota de tier retorna 404 quando o pacote está ausente. A rota não é registrada, então o roteador não encontra correspondência para ela. Isso é esperado; não é uma falha de autenticação.

• 401 versus 403. 401 significa que a requisição não tem uma chave válida, e a resposta inclui um header WWW-Authenticate: Bearer conforme o RFC 9110 §11.6.1. 403 significa que a chave é válida, mas o tier dela não tem direito à operação.

• As sessões ficam desativadas por padrão. As rotas /api/v1/sessions/... existem apenas quando NEXTPDF_SESSIONS_ENABLED=true e há ferramentas disponíveis.

• As operações de alto risco continuam passando por gate. Uma chamada REST que aciona uma ferramenta ApprovalRequired passa pelo mesmo gate human-in-the-loop que o Model Context Protocol (MCP). Consulte /connect/hitl-risk-tiers/.

Desempenho

Cada worker do RoadRunner atende a uma requisição por vez. Renderizações síncronas longas ocupam um worker. Use as rotas de jobs assíncronos para trabalhos lentos, liberando os workers. Dimensione o pool de acordo com a latência observada; consulte /connect/production-usage/.

Notas de segurança

Faça a terminação de Transport Layer Security (TLS) à frente do listener REST. O listener expõe HTTP em texto plano por design e espera um terminador upstream. Autentique com uma chave npk_live_ suficientemente aleatória, armazene as chaves fora do controle de versão e prefira o key store baseado em arquivo com recarregamento a quente. Consulte /connect/security-and-operations/.

Conformidade

Afirmação	Fonte	reference_id
401 DEVE carregar um WWW-Authenticate como desafio	RFC 9110 §11.6.1
Os métodos seguros são somente leitura	RFC 9110 §9.2.1
As requisições PSR-7 são imutáveis	PSR-7 §3.2.1
Um middleware incapaz de produzir a resposta delega ao request handler fornecido	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Contexto comercial

As rotas de assinatura, redação, comparação, acessibilidade, otimização e compliance aparecem apenas quando o nextpdf/premium está instalado. O modelo de autenticação permanece inalterado; o tier da chave define o acesso.

Consulte também

• /connect/quickstart/ — a requisição de renderização executável
• /connect/security-and-operations/ — autenticação e postura de TLS
• /connect/production-usage/ — jobs, idempotência, rate limiting
• /transports/mcp/ · /transports/grpc/ — os demais transportes
• /connect/tool-catalog/ — como o conjunto de rotas é mapeado para o catálogo de ferramentas