Generate a New Api Object

Source: R/grist.R

The grist_api generator creates a new object, which is the class containing simple methods to call an api Grist. The class is based on the R6. This work follows the Grist API references https://support.getgrist.com/api/ from July 2025, and is based on the Python module grist_api https://github.com/gristlabs/py_grist_api/ and the Linux R package, gristr https://forge.ird.fr/phim/cunnac/gristr

Initialization

A new 'grist_api'-object is initialized using the new() method on the generator:

api <- grist_api$new( server = 'https://grist.numerique.gouv.fr', api_key = Sys.getenv("GRIST_KEY"), doc_id = Sys.getenv("GRIST_DOC_TEST") )

Value

A new 'grist_api'-object

JSON string or list()

A tibble::tibble() object.

A JSON string

Methods

Public methods

Method new()

Create a new grist_api object

Usage

grist_api$new(server = NULL, api_key = NULL, doc_id = NULL)

Arguments

server

string. IP or URL with protocol (http or https)

api_key

string. your Grist token

doc_id

string. the internal doc ref in setting > API

Method print()

print the doc metadata of grist_api object

Usage

grist_api$print(...)

Arguments

...

Passed...

Method call()

Low-level interface that returns the REST call result as json

Usage

grist_api$call(
  url,
  json_data = NULL,
  method = NULL,
  prefix = NULL,
  type_resp = "list"
)

Arguments

url

The part of the URL after api/doc/doc_id or other prefix. OBLIGATORY

json_data

A JSON string with records to patch, put, delete or post. Default NULL

method

Http method to use ('GET', 'POST', 'DELETE', 'PUT', 'PATCH'). Default 'GET' or 'POST' with data

prefix

To use a call other than api/doc/doc_id. Default NULL

type_resp

Set the output type string or list. Default "list"

Method json_to_table()

Convert a Grist json response string to a table

Usage

grist_api$json_to_table(json_data, structure)

Arguments

json_data

A JSON string. OBLIGATORY

structure

The name of the Grist response encapsulating structure. Usually "tables", "records". OBLIGATORY

Method table_to_json()

Convert a data.frame of records to a json string

Usage

grist_api$table_to_json(records, mode = "modify", key_cols = NULL)

Arguments

records

A data.frame()

mode

"add", "modify" or "sync".

key_cols

A vector of columns (grist_col_id) constituting a unique key. only for "sync" mode

Method clone()

The objects of this class are cloneable with this method.

Usage

grist_api$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Working only if Env Var "GRIST_KEY" and "GRIST_DOC_TEST" are defined

# Create a New Api Object on a single grist document
api <- grist_api$new(
  server = 'https://grist.numerique.gouv.fr',
  api_key = Sys.getenv("GRIST_KEY"),
  doc_id = Sys.getenv("GRIST_DOC_TEST")
)