Skip to main content

Querying an authenticated API (Twitter)

Many APIs require some form of authentication. This can be a token, an OAuth flow, or another mechanism. The api command is able to send requests with custom headers and data payloads, and also includes a --bearer flag among other auth related flags to support many forms of API authentication.

The oauth command also works for a number of supported OAuth providers, as well as custom Client Credentials flows.

Example 1: Twitter​

Full Query​

api get "https://api.twitter.com/2/tweets/search/recent?query=NASA&tweet.fields=created_at,author_id,public_metrics&max_results=100"
--bearer "$CREDENTIALS.twitter_bearer$"
|| normalize data

Note: This query requires a preconfigured twitter_bearer custom credential. See credentials docs for more.

Stage 1: Making an authenticated request​

api get "https://api.twitter.com/2/tweets/search/recent?query=NASA&tweet.fields=created_at,author_id,public_metrics&max_results=100"
--bearer "$CREDENTIALS.twitter_bearer$"

This stage will make a GET request to the Twitter search API. The --bearer flag contains the internal token CREDENTIALS.twitter_bearer$ that will be substituted with the preconfigured twitter_bearer custom credential value before dispatching the request.

Alternatively, you could manually construct the --headers for this query.

api get "https://api.twitter.com/2/tweets/search/recent?query=NASA&tweet.fields=created_at,author_id,public_metrics&max_results=100"
--headers '{"Authorization": "$CREDENTIALS.twitter_bearer$"}'

Stage 2: Normalizing the results​

...
|| normalize data

The results from this endpoint are nested in a data array. Note the data.0.*, data.1.* etc. columns. We can expand the results array into a row per data using the normalize command.

Example 2: Reddit OAuth​

Full Query​

oauth
  --credential "reddit"
|| api get https://oauth.reddit.com/r/sacramento/hot.json
  --token.access_token "$token.access_token$"
  --useragent "api:com.acmeinc:v1.0.0 (by u/acmeinc)"
|| normalize data.children

Note: This query requires a preconfigured reddit OAuth token. See Reddit OAuth docs for instructions.

Stage 1: Acquiring OAuth Token​

oauth
  --credential "reddit"

We can use the oauth command with a preconfigured reddit credential to get back a token to use for future requests. The token will be in the token.access_token column.

Stage 2: Making an authenticated request​

...
|| api get https://oauth.reddit.com/r/sacramento/hot.json
  --token.access_token "$token.access_token$"
  --useragent "api:com.acmeinc:v1.0.0 (by u/acmeinc)"

In the seconds stage, we will make a request to the Reddit API to get top posts from the sacramento subreddit. This request requires authentication and identification. We will identify our request using the --useragent flag set to our Reddit username. The request will be authorized using the --token.access_token flag, which will contain a $token.access_token$ token that will be replaced by the token.access_token column value from the previous oauth command stage.

Stage 3: Normalizing the results​

...
|| normalize data.children

The results from this endpoint are nested in a data.children array. Note the data.children.0.*, data.children.1.* etc. columns. We can expand the data.children array into a row per data using the normalize command.