Managing Content

This section explains how to use the Connect Server APIs to obtain details about your existing content and perform updates. See the Deploying Content section for help creating content and deploying your code.

The content APIs are experimental and will continue to evolve in upcoming RStudio Connect releases. Please try using these APIs to build your own deployment tools. Let your Customer Success representative know about your experience!

Not all operations are supported by the Connect Server APIs. Please use the RStudio Connect dashboard for changes not yet available in the API.

These recipes use bash snippets and rely on curl to perform HTTP requests. We use the CONNECT_SERVER and CONNECT_API_KEY environment variables introduced in the Getting Started section of this cookbook.

Read a Content Item

One of your most common operations will be to read the current state for a content item. The GET /experimental/content/{guid} get content endpoint can tell you its name, the runtime fields, and lots of other information.

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    "${CONNECT_SERVER}__api__/v1/experimental/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# => {
# =>   "guid": "ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5",
# =>   "name": "shakespeare",
# =>   "title": "Shakespeare Word Clouds",
# =>   ...
# =>   "init_timeout": null,
# =>   "min_processes": null,
# =>   ...
# => }

The Connect Server API Reference describes all the response fields for the GET /experimental/content/{guid} get content endpoint.

Update a Single Content Item Field

The first thing we want to change is the content title; our team has decided to rename this content from "Shakespeare Word Clouds" to "Word Clouds from Shakespeare". It's a small change that we can make with a call to the POST /experimental/content/{guid} update content endpoint:

export DATA='{"title": "Word Clouds from Shakespeare"}'
curl --silent --show-error -L --max-redirs 0 --fail -X POST \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/experimental/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# => {
# =>   "guid": "ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5",
# =>   "name": "shakespeare",
# =>   "title": "Word Clouds from Shakespeare",
# =>   ...
# =>   "init_timeout": null,
# =>   "min_processes": null,
# => }

The JSON object returned by the update is the result of our changes and has the same shape as the read call.

In this example, we are including only title - the single field we want to change. You can make an update call using any portion of the content object as the POST payload. Fields in the JSON payload receive updates and other fields remain unchanged. The Connect Server API Reference describes all the request and response fields for the POST /experimental/content/{guid} update content endpoint.

Fields marked "read-only" are ignored by the update operation. Read-only fields are computed internally by RStudio Connect as other operations occur.

Update Multiple Content Item Fields

We can update other fields with the same approach we used when updating title in our previous example. The title update changed one field; our next example updates two fields that we want to manage together.

Let's assume that our application has a fairly expensive startup. The developer is working to shorten its initialization, but that effort is not complete.

We want to allow additional time for that initialization and leave an instance of that process running at all times. We will adjust the init_timeout and min_processes settings.

export DATA='{"init_timeout": 300, "min_processes": 2}'
curl --silent --show-error -L --max-redirs 0 --fail -X POST \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/experimental/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# => {
# =>   "guid": "ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5",
# =>   "name": "shakespeare",
# =>   "title": "Word Clouds from Shakespeare",
# =>   ...
# =>   "init_timeout": 300,
# =>   "min_processes": 2,
# => }

That application is now configured to keep two processes running on each server and allows up to five minutes for successful startup.

We can undo the changes to init_timeout and min_processes after performance improvements to the Shiny application have been deployed. The init_timeout and min_processes had a null value before we applied our first set of changes.

The content item fields related to process execution can take a null value, which indicates to use the associated system default. A non-null value overrides the default for that specific property. The Content definition in the Connect Server API Reference describes which fields have server configuration defaults.

Here is an update request that gives a null value to both init_timeout and min_processes.

export DATA='{"init_timeout": null, "min_processes": null}'
curl --silent --show-error -L --max-redirs 0 --fail -X POST \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/experimental/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# => {
# =>   "guid": "ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5",
# =>   "name": "shakespeare",
# =>   "title": "Word Clouds from Shakespeare",
# =>   ...
# =>   "init_timeout": null,
# =>   "min_processes": null,
# => }