Check version for document by REST API

BiBo · November 16, 2023, 9:28pm

Hello. I want to try downloading by REST API reference - Grist Help Center. when doc is changed. Is it possible to somehow track/compare the version .grist files in Grist-server and on remote server by API? And use downloadDoc endpoint when version is different.

paul-grist · November 16, 2023, 9:45pm

Hmm. There are two undocumented endpoints:

/api/docs/DOCID/states
/api/docs/DOCID/snapshots

Both will give output that changes as the document changes. If you don’t have snapshots set up, the /snapshots endpoint won’t give a lot of information, but it will give a timestamp. The /states endpoint lists hashes and ids of changes made to the document. Different versions of the document could be compared somewhat with this information. Not sure exactly what you need.

Here are example endpoints for a template document:

Again, /snapshots will look a lot emptier if the feature is not set up, but it will have a lastModified timestamp.

BiBo · November 17, 2023, 6:16am

Thank you, this is a very interesting opportunity. /states takes into account all changes since the beginning of the document creation? Well, this information can be obtained from the metadata of the saved file .grist?

paul-grist · November 17, 2023, 2:19pm

The length of /states will eventually be truncated for a long lived document or a document with very big changes:

github.com

gristlabs/grist-core/blob/d8b224b45dd8cc9c6452f223f4670325ead1377b/app/server/lib/ActionHistoryImpl.ts#L16-L23


      
          // History will from time to time be pruned back to within these limits
          // on rows and the maximum total number of bytes in the "body" column.
          // Pruning is done when the history has grown above these limits, to
          // the specified factor.
          const ACTION_HISTORY_MAX_ROWS = 1000;
          const ACTION_HISTORY_MAX_BYTES = 1000 * 1000 * 1000;  // 1 GB.
          const ACTION_HISTORY_GRACE_FACTOR = 1.25;  // allow growth to 1250 rows / 1.25 GB.
          const ACTION_HISTORY_CHECK_PERIOD = 10;    // number of actions between size checks.

The information shown in /states can indeed be obtained from the .grist file, it is in the _gristsys_ActionHistory table.

BiBo · November 17, 2023, 7:42pm

Here the task is to compare the current version. grist file with the document version, so I think the number of /states is not particularly important. One of the use cases, I think, is the offline operation of a mobile application (I’m just starting to experiment with this).