https://github.com/posit-dev/connectapi
An R package for interacting with the RStudio Connect Server API
https://github.com/posit-dev/connectapi
api-client package rstats rstudio-connect
Last synced: 7 days ago
JSON representation
An R package for interacting with the RStudio Connect Server API
- Host: GitHub
- URL: https://github.com/posit-dev/connectapi
- Owner: posit-dev
- License: other
- Created: 2019-01-23T20:32:57.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-01-21T18:39:51.000Z (about 1 year ago)
- Last Synced: 2025-01-23T08:35:59.746Z (about 1 year ago)
- Topics: api-client, package, rstats, rstudio-connect
- Language: R
- Homepage: https://pkgs.rstudio.com/connectapi/
- Size: 5.47 MB
- Stars: 46
- Watchers: 20
- Forks: 26
- Open Issues: 59
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
[](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[](https://cran.r-project.org/package=connectapi)
[](https://app.codecov.io/gh/posit-dev/connectapi?branch=main)
[](https://github.com/posit-dev/connectapi/actions/workflows/R-CMD-check.yaml)
# connectapi 
This package provides an R client for the [Posit Connect Server
API](https://docs.posit.co/connect/api/), as well as helpful functions that
utilize the client.
It is designed to work with all supported versions of Connect, though some features may only be available to newer versions.
## Installation
To install from CRAN:
```r
install.packages("connectapi")
```
To install the development version:
```r
remotes::install_github('posit-dev/connectapi')
```
## Client
To create a client:
```{r, eval = FALSE}
library(connectapi)
client <- connect(
server = "https://connect.example.com",
api_key = ""
)
```
You can also define the following environment variables (in a `.Renviron` file, for instance):
```
CONNECT_SERVER = https://connect.example.com
CONNECT_API_KEY = my-secret-api-key
```
These environment variable values will be used automatically if defined in your R session.
```{r, eval = FALSE}
library(connectapi)
client <- connect()
```
## Getting Started
Once a client is defined, you can use it to interact with Posit Connect.
### Exploring Data
You can use the `get_` methods to retrieve data from the Posit Connect server.
```r
library(connectapi)
client <- connect()
# get data
users <- 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 content
all_content <- get_content(client, limit = Inf)
```
### Deployment
The `rsconnect` package is usually used for deploying content to Connect.
However, if you want to use programmatic deployment with the Posit Connect
Server API, then these `connectapi` helpers should be useful!
```{r, eval = FALSE}
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 content
content %>%
set_thumbnail("./my/local/image.png")
content %>%
set_thumbnail("http://url.example.com/image.png")
# set image and a vanity URL
content %>%
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 content
client %>%
content_item("the-content-guid") %>%
set_vanity_url("/another-awesome-app")
# migrate content to another server
client_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 item
client_prod %>% browse_dashboard()
client_prod %>% browse_solo()
# open a browser to the docs
client_prod %>% browse_api_docs()
```
## Troubleshooting and FAQ
**Access Denied Errors?**
This is likely due to either (1) `Connect$server` or `Connect$api_key` being
defined improperly or (2) you do not have access to the Posit Connect cluster
to do the operation in question
**Warning about version numbers**
We test the package against a range of versions of Connect, as old as
`2022.10.0`. If your Connect server is older than that, the
package may still 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 create
inconsistencies between versions as a result. To mitigate this, we recommend:
- Track the version of `connectapi` in use for your applications by using `renv`
- Test high value content that uses `connectapi` before updating `connectapi` or Posit Connect
- Update Posit Connect to the latest version _first_ when an update to `connectapi` is needed
**Error - Need to update Posit Connect**
As a helpful clarification for users, we have added error messages to API
requests when the version implemented in the package specifically introduces a
backwards incompatible dependency on older versions of Posit Connect.
If you get this error message, our recommendation would be:
- Look at [`NEWS.md`](./NEWS.md) to find the moment the change was introduced
- Downgrade `connectapi` to the previous version of the package
- (Advanced) Use the "blame" feature on GitHub to track commits and find out when the error was introduced
Please feel free to open an Issue if you think there is a bug, or ask a
free-form question on [Posit
Community](https://forum.posit.co/c/posit-professional-hosted/posit-connect/27)
**Other ideas for FAQs or Common Issues?**
Please open an issue or PR! We would love to have your contribution!
## Code of Conduct
Please note that the connectapi project is released with a [Contributor Code of
Conduct](https://posit-dev.github.io/connectapi/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.