Server API Best Practices

Below are some recommendations on how to best use PSPDFKit Server.

Use PSPDFKit Server as a Source of Truth for Annotations

When multiple users are editing a document concurrently, editing conflicts will occur. For example, one user might move an annotation to the left, while another user might change the annotation’s color.

If you replicate annotations from PSPDFKit Server to your own database and back, the same conflicts will occur between your database and PSPDFKit Server’s database.

By not relying on PSPDFKit Instant’s conflict resolution, changes from your database will overwrite changes made by your users, or vice versa.

PSPDFKit Instant has built-in support for handling concurrent edits and resolving conflicts. From your user’s perspective, concurrent editing will simply work, just like they expect.

Instead, use the CRUD (create, read, update, and delete) operations of the Annotations API, which give your backend full access to all annotations.

Copy a Template Document Instead of Uploading It Multiple Times

Often you need to give multiple users an independent version of one document. For example, your users might have access to a library of PDF files and can add private annotations to them.

Instead of repeatedly uploading the same (potentially large) PDF file to PSPDFKit Server, upload it once and store its document ID in your backend’s database. This is the template document, which you should never modify or let users access with write permission.

Each time a user requests this document for the first time, use the copy_document API to efficiently create a copy of this document for them, which they can then edit.