Skip to content

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.

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

Note

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.

List Content Items#

You can retrieve detailed information about the content that is available on your Connect instance using the GET /v1/content/ endpoint. The endpoint will return detailed information on all content items that are currently visible to you (as determined by your API key). If you are an administrator, all content items will be returned to you regardless of visibility and permissions.

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

In addition to listing all content, you can also filter by both the name and/or the owner of the content using the name and owner_guid request parameters. Keeping in mind that content names only need to be unique within the scope of each owner, this can be especially useful for finding individual content items where you do not know the specific guid of the content. For example:

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    "${CONNECT_SERVER}__api__/v1/content?name=shakespeare"
# => {
# =>   "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 request parameters and response fields for the GET /v1/content/ endpoint.

Read a Content Item#

You can retrieve detailed information about a specific item using the GET /v1/content/{guid} endpoint which 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/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 /v1/content/{guid} endpoint.

Update a Content Item#

The PATCH /v1/content/{guid} endpoint is used to update a content item.

Update a Single Content Item Field#

After content has been created, you may wish to update a single field of the content item. For this example, the first thing we want to change is the content's 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 PATCH /v1/content/{guid} endpoint:

export DATA='{"title": "Word Clouds from Shakespeare"}'
curl --silent --show-error -L --max-redirs 0 --fail -X PATCH \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/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 schema as the read call.

In this example, we are only including title, which is the single field we want to change. 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 PATCH /v1/content/{guid} endpoint.

Note

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 that we used when updating the 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 PATCH \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/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.

Note

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 PATCH \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/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,
# => }

Update Content Ownership#

When a single designated publisher or administrator account is used to deploy all content items, it is often desirable to return content ownership to the orignial developer so that they can assume responsibility for content management tasks going forward.

Administrators can reassign content ownership by updating the owner_guid field. Use the JSON DATA payload to set the owner_guid to the GUID of the new user. The new user must have a role of Publisher or Administrator. Viewers cannot be content owners.

This pattern is simply a variant of the single field update recipe discussed previously.

export DATA='{"owner_guid": "32db99f1-7d4c-47e7-878p-47c162ea8000"}'
curl --silent --show-error -L --max-redirs 0 --fail -X PATCH \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    --data "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# => {
# =>   "guid": "ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5",
# =>   "name": "shakespeare",
# =>   "title": "Word Clouds from Shakespeare",
# =>   ...
# => }

The JSON object returned by the update is the result of our changes and has the same schema as the read call. Fields in the JSON payload receive updates and other fields remain unchanged.

Delete a Content Item#

You can delete a content item using the DELETE /v1/content/{guid} endpoint.

Warning

Deleting content is a destructive operation and cannot be reversed, so use with caution.

curl --silent --show-error -L --max-redirs 0 --fail -X DELETE \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    "${CONNECT_SERVER}__api__/v1/content/ccbd1a41-90a0-4b7b-89c7-16dd9ad47eb5"
# =>

A successful request will return a 204 HTTP status code with an empty response.

The Connect Server API Reference describes all the response details for the DELETE /v1/content/{guid} endpoint.

Copyright © RStudio, PBC. All Rights Reserved