Accessing Content

Using an API Key

This section contains examples of how to use API Keys to obtain or interact with content deployed to Posit Connect. These examples assume that your Posit Connect API Key is available in the environment variable CONNECT_API_KEY.

export CONNECT_API_KEY=q9R4ylb3K3RPB7AB46il8mxjjcYsaClW

The examples in this section use the curl command-line utility to perform basic authenticated API Key requests against content hosted by Posit Connect.

The API Keys from Code section shows how to make these same requests from R and Python. The Connect Server API Cookbook contains recipes which interact with the Connect Server API using API Keys.

Static Content

You can use API Keys to download resources associated with static content (plots and previously rendered HTML).

Assume you have published a plot to Posit Connect and it has the URL: http://rsc.company.com/content/24/target.html.

Download this content using your API Key and the curl command-line program:

curl -O -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://rsc.company.com/content/24/target.html"

The -O option tells curl to write a file named by the remote filename. In this case, it would write to the target.html file.

Write to a different filename (output.html in this example) using the -o option:

curl -o output.html -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://rsc.company.com/content/24/target.html"

Plumber

You can use API Keys to interact with a Plumber API.

Using the plumber API definition:

## plumber.R

#* @get /mean
normalMean <- function(samples=10){
  data <- rnorm(samples)
  mean(data)
}

The function normalMean is exposed through the /mean endpoint. It takes an optional samples query argument.

Assume this Plumber API is available on Posit Connect with the URL: http://rsc.company.com/content/24/.

You can call this API using an API Key and the curl command-line program:

curl -H "Authorization: Key ${CONNECT_API_KEY}" \
    "http://rsc.company.com/content/24/mean?samples=5"

Using API Keys from Code

The Plumber and static content examples show that we can access different types of content using API Keys. Those requests use the command-line utility curl. This section shows how to use API Keys from your R and Python code.

All of these examples assume that your Posit Connect API Key is available in the environment variable CONNECT_API_KEY and the base URL to your Posit Connect server is in the CONNECT_SERVER environment variable.

export CONNECT_API_KEY=q9R4ylb3K3RPB7AB46il8mxjjcYsaClW
export CONNECT_SERVER=https://rsc.company.com/

R with httr

The httr package lets you make HTTP requests from R. This example performs an HTTP GET request against the same Plumber API we used earlier with curl.

library(httr)

connectServer <- Sys.getenv("CONNECT_SERVER")
connectAPIKey <- Sys.getenv("CONNECT_API_KEY")

resp <- httr::GET(connectServer, 
    path = "/content/24/mean", 
    query = list(samples = 5),
    add_headers(Authorization = paste0("Key ", connectAPIKey)))
result <- httr::content(resp, as = "parsed")

The result object is defined by parsing the JSON response data. It contains the result computed by normalMean in our Plumber API.

Python3 with urllib

The urllib package is a collection of modules for working with URLs. It is part of the Python3 standard library. This example performs an HTTP GET request against the Plumber API we used earlier.

# -*- coding: utf-8 -*-
import json
import os
import urllib.parse
import urllib.request

connect_server = os.getenv("CONNECT_SERVER")
connect_api_key = os.getenv("CONNECT_API_KEY")

def build_url(base, path, **kwargs):
    query = urllib.parse.urlencode(kwargs)
    parts = urllib.parse.urlparse(base)
    parts = parts._replace(path = path, query = query)
    return parts.geturl()

headers = { "Authorization": "Key %s" % connect_api_key }

request_url = build_url(connect_server, "/content/24/mean", samples = 5)
request = urllib.request.Request(request_url, headers = headers)
response = urllib.request.urlopen(request)
data = response.read()
encoding = response.info().get_content_charset("utf-8")
result = json.loads(data.decode(encoding))

The result object is defined by parsing the JSON response data. It contains the result computed by normalMean in our Plumber API.