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 Posit 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 Posit 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 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.

Updating a Content Item’s Kubernetes Service Account

We can update the service_account_name field following the same approach we used to update the title in our previous example.

Service account updates require the following:

Only an administrator can update the service_account_name field on a content item.
A non-null service_account_name value must be a valid Kubernetes service account name. If the value does not adhere to Kubernetes naming conventions, an error is returned. Read more about Kubernetes service accounts here.
If validation is enabled, any non-null service_account_name value in the API input must be known to Connect. Read more about service account validation here.

Let’s consider the scenario where an administrator would like to remove the service_account_name value on an existing content item.

We can accomplish this with a call to the PATCH /v1/content/{guid} endpoint, with service_account_name set to null:

export DATA='{"service_account_name": 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",
# =>   ...
# =>   "service_account_name" : null,
# => }

For more information about the service_account_name field, you can reference the API Guide.

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.