Managing Content

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

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

These recipes use bash snippets and rely on curl to perform HTTP requests. These recipes 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 returns 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 are 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 might want to update a single field of the content item. For this example, the first thing to change is the content’s title. The team has decided to rename this content from “Shakespeare Word Clouds” to “Word Clouds from Shakespeare.”

It’s a small change that you 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 these changes and has the same schema as the read call.

In this example, you are only including title, which is the single field you 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 Connect as other operations occur.

Update multiple content item fields

You can update other fields with the same approach used when updating the title in the previous example. The title update changed one field, while the next example updates two fields that you will want to manage together.

Assume that the application has a fairly expensive startup. The developer is working to shorten its initialization, but that effort is not complete.

You want to allow additional time for that initialization and leave an instance of that process running at all times. You can start by adjusting 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.

You 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 applying the 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 original developer. This lets them 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 these 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

You can update the service_account_name field following the same approach used to update the title in the previous example.

Service account updates require the following:

  1. An administrator account. Only an administrator can update the service_account_name field on a content item.

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

  3. If validation is enabled, any non-null service_account_name value in the API input must be known to Connect. For more information, see the Service Account Validation appendix.

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

You 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, see the API Reference.

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