Migration

This page tracks breaking changes between releases of github.com/poli-page/sdk-go. Before 1.0, a breaking change bumps the minor version. For the full per-release diff, see the changelog.

From 0.9.x to 0.11.0

0.10.0 was never released for Go: 0.11.0 follows 0.9.0 and carries both groups of changes below.

Environments replace versions

An API key now names its environment (pp_{env}_…), and a render uses the project’s copy published in that environment. Template versions, the template preview and inline-HTML rendering are gone from the API, so they are gone from the SDK, with no deprecation window.

• Rename polipage.ProjectModeInput to polipage.RenderInput, and drop its Version field. polipage.Opt is gone with it. Publish the project to the key’s environment instead of pinning a version.
• Render.Preview, InlineModeInput and PreviewResult are removed. Try a template or raw HTML in the playground at play.poli.page. Documents.Preview (the stored HTML of a rendered document) stays.
• DocumentDescriptor.Version is removed. DocumentDescriptor.Environment is a plain string, and the Environment type and its EnvironmentSandbox/EnvironmentLive constants are removed: compare with "sandbox", "live" or your own environment names.
• Use sandbox keys (pp_sandbox_…) where you used test keys. Standard and service keys share the one pp_{env}_… format; see Authentication.
• Replace the removed error codes and sentinels:
  • VERSION_NOT_FOUND, INVALID_VERSION_FORMAT, VERSION_REQUIRED, INVALID_VERSION_FOR_KEY_ENV and ErrVersionNotFound: a render now fails with PROJECT_NOT_FOUND, PROJECT_NOT_IN_ENVIRONMENT or TEMPLATE_NOT_FOUND.
  • GONE and ErrGone: use DOCUMENT_GONE and ErrDocumentGone.
  • PAYMENT_REQUIRED and ErrPaymentRequired: past-due billing is reported as ORGANIZATION_PAYMENT_GRACE.
  • MISSING_PROJECT_OR_TEMPLATE is removed.
• ThumbnailOptions.Width is optional: a zero value is not sent and the API uses 400 px.

The full list is in CHANGELOG.md and MIGRATION.md.

API contract v1.3.0

The SDK now follows the retry policy and the error messages of the Poli Page API contract. The full guide is in MIGRATION.md in the repo.

• QUOTA_EXCEEDED and OVERAGE_CAP_EXCEEDED (429) and STORAGE_ACCESS_DENIED (502) are no longer retried, and IsRetryable() returns false for them. A queue that requeues on IsRetryable() now drops these errors at once: handle them by code. See Retries and idempotency.
• DOWNLOAD_FAILED is never retryable: IsRetryable() is false for it whatever the storage status (it was true for a storage 5xx or 429). Call Documents.Get for a fresh URL and download again.
• Retry-After: 0 retries at once; only integer seconds and HTTP-dates are read.
• The SDK-side messages are the specification’s exact texts (apiKey is required, Network request failed, Request timed out after <ms>ms, Request was aborted, Failed to download PDF: HTTP <status>, Failed to download PDF: network error, HTTP <status> for a non-JSON error body, project is required). Match Code, not the message. See Errors.
• Canceling the context during the PDF download returns aborted, not DOWNLOAD_FAILED.

See also

• Changelog
• Render input