Repository files navigation

This package provides an R client for thePosit Connect ServerAPI, as well as helpful functionsthat utilize the client. It is designed to work with all supportedversions of Connect, though some features may only be available to newerversions.

To install from CRAN:

install.packages("connectapi")

To install the development version:

remotes::install_github('posit-dev/connectapi')

To create a client:

library(connectapi)client<- connect(server="https://connect.example.com",api_key="<SUPER SECRET API KEY>")

You can also define the following environment variables (in a.Renviron file, for instance):

CONNECT_SERVER  = https://connect.example.comCONNECT_API_KEY = my-secret-api-key

These environment variable values will be used automatically if definedin your R session.

library(connectapi)client<- connect()

Once a client is defined, you can use it to interact with Posit Connect.

You can use theget_ methods to retrieve data from the Posit Connectserver.

library(connectapi)client<- connect()# get datausers<- get_users(client)groups<- get_groups(client)usage_shiny<- get_usage_shiny(client)usage_static<- get_usage_static(client)some_content<- get_content(client)# get all contentall_content<- get_content(client,limit=Inf)

Thersconnect package is usually used for deploying content toConnect. However, if you want to use programmatic deployment with thePosit Connect Server API, then theseconnectapi helpers should beuseful!

library(connectapi)client<- connect()# deploying content# NOTE: a `manifest.json` should already exist from `rsconnect::writeManifest()`bundle<- bundle_dir("./path/to/directory")content<-client %>%  deploy(bundle,name="my-app-name") %>%  poll_task()# set an image for contentcontent %>%  set_thumbnail("./my/local/image.png")content %>%  set_thumbnail("http://url.example.com/image.png")# set image and a vanity URLcontent %>%  set_thumbnail("./my/local/image.png") %>%  set_vanity_url("/my-awesome-app")# change access_type to "anyone"content$update(access_type="all")# edit another piece of contentclient %>%  content_item("the-content-guid") %>%  set_vanity_url("/another-awesome-app")# migrate content to another serverclient_prod<- connect(server="prod.example.com",api_key="my-secret-key")prod_bnd<-client %>%  content_item("the-guid-to-promote") %>%  download_bundle()client_prod %>%  deploy(prod_bnd,title="Now in Production") %>%  set_vanity_url("/my-app")# open a browser to the content itemclient_prod %>% browse_dashboard()client_prod %>% browse_solo()# open a browser to the docsclient_prod %>% browse_api_docs()

Access Denied Errors?

This is likely due to either (1)Connect$server orConnect$api_keybeing defined improperly or (2) you do not have access to the PositConnect cluster to do the operation in question

Warning about version numbers

We test the package against a range of versions of Connect, as old as2022.10.0. If your Connect server is older than that, the package maystill work.

We strive to:

• track the latest version of the Posit Connect API
• add new features as they come available and have demand
• maintain backwards compatibility

These priorities are sometimes at odds, and sometimes they createinconsistencies between versions as a result. To mitigate this, werecommend:

• Track the version ofconnectapi in use for your applications byusingrenv
• Test high value content that usesconnectapi before updatingconnectapi or Posit Connect
• Update Posit Connect to the latest versionfirst when an update toconnectapi is needed

Error - Need to update Posit Connect

As a helpful clarification for users, we have added error messages toAPI requests when the version implemented in the package specificallyintroduces a backwards incompatible dependency on older versions ofPosit Connect.

If you get this error message, our recommendation would be:

• Look atNEWS.md to find the moment the change wasintroduced
• Downgradeconnectapi to the previous version of the package
• (Advanced) Use the “blame” feature on GitHub to track commits and findout when the error was introduced

Please feel free to open an Issue if you think there is a bug, or ask afree-form question onPositCommunity

Other ideas for FAQs or Common Issues?

Please open an issue or PR! We would love to have your contribution!

Please note that the connectapi project is released with aContributorCode ofConduct.By contributing to this project, you agree to abide by its terms.