Print this page
In this topic
The examples in this topic illustrate how to query the API using Windows PowerShell.
Tip: The Ringtail SDK includes a toolkit with sample code and explanations of additional ways that you can interact with the Ringtail Connect API using third-party applications. To get access to the UI Extension SDK, contact info@ringtail.com.
Before you start, do the following:
●Obtain your Ringtail API token and API key from your system administrator. Your token and key authenticate you. For more information, see Obtain an API token and key for a user.
Caution: Store your API token and key in a secure location, the same way that you protect your password. Anyone who has your token and key can access all of the data that you can access through the API.
●Obtain the URL of the API service for the portal from your system administrator. The URL of the API service is available in the Portal Management area, in the Settings section, on the Portal Options page. For more information, see Ringtail Connect API URL.
Use the following sample PowerShell GET request as a starting point to perform operations in PowerShell.
$uriPrefix = "URL of the API service for the portal?q="
$token = "Your API token"
$key = "Your API key"
$query = "{ users { userName } }"
$uri = $uriPrefix + [uri]::EscapeDataString($query)
$request = [System.Net.WebRequest]::Create($uri)
$request.Method = "GET"
$request.Headers["Authorization"] = "Bearer $token"
$request.Headers["ApiKey"] = $key
$result = $request.GetResponse()
$stream = $result.GetResponseStream()
$reader = New-Object IO.StreamReader($stream)
$reader.readToEnd()
In the request, provide values for the following elements:
●The URL of the API service for the portal, such as http://ringtail.com/Ringtail-Svc-Portal/api/query. Make sure that the URL is followed by ?q=. For more information, see Before you start.
●Your API token.
●Your API key.
●The operation to run, formatted as valid JSON syntax. The sample request encodes the JSON query into valid syntax that can be passed as part of a URL.
For information about how to create and test queries in the API explorer before running queries in a third-party application, see Access and use the Ringtail Connect API Explorer.
Use the following sample PowerShell POST request as a starting point to perform operations in PowerShell.
$uri = "URL of the API service for the portal"
$token = "Your API token"
$key = "Your API key"
$body = "{""query"":""{ users { userName }}""}"
$request = [System.Net.WebRequest]::Create($uri)
$request.ContentType = "application/json"
$request.Method = "POST"
$request.Headers["Authorization"] = "Bearer $token"
$request.Headers["ApiKey"] = $key
$stream = $request.GetRequestStream()
$stream.Write([byte[]][char[]]$body, 0, $body.Length)
$result = $request.GetResponse()
$stream = $result.GetResponseStream()
$reader = New-Object IO.StreamReader($stream)
$reader.readToEnd()
In the request, provide values for the following elements.
●The URL of the API service for the portal, such as http://ringtail.com/Ringtail-Svc-Portal/api/query. For more information, see Before you start.
●Your API token.
●Your API key.
●The operation to run, formatted as valid JSON syntax. Use outer double quotation marks.
For information about how to create and test queries in the API explorer before running queries in a third-party application, see Access and use the Ringtail Connect API Explorer.
