How can we help?

Guide to REST API data sources and data feeds

In Klipfolio, data from web services is accessed either by a dedicated service connector in Klipfolio or by using the REST/URL connector which can connect to most APIs that use the REST (REpresentational State Transfer) protocol and one of the following authentication methods (if authentication is required):

Note: REST APIs with additional authentication requirements, such as an initial login request, may not be accessible using Klipfolio's REST/URL connector.

This article includes:

How to read an API query

Each web service API has its own unique definition and requirements. We recommend you refer to the web service API documentation for specific details about:

  • user credentials (for example, username and password)
  • authentication method (OAuth, basic HTTP, 2-step Auth or API Key)
  • web service URL (address of the web service being queried, for example, http://api.linkedin.com)
  • endpoint names (the resources available to be queried, for example, in http://api.linkedin.com/v1/people, people is the endpoint)
  • parameters
    • dimensions, such as time or geographic location
    • metrics, the data being requested
    • time span, usually specified by start and end dates
  • parameter formats, in particular date formats (for example, yyyy-MM-dd, Unix time)
  • parameter combinations (which metrics can be used with which dimensions)
  • access method (GET, POST)
  • output format (CSV, JSON, XML)

API query syntax

Although there is no defined REST standard, many REST-based API queries use a syntax similar to:

<webServiceURL>/<version>/<endpointName>.<outputFormat>?<parameter1Name>=<parameter1Value>&<parameter2Name>=<parameter2Value>&<startDate>=01-01-2015&<endDate>={date.today}

A REST-based query may not include all of the elements shown above. If the query includes parameters, the first parameter is prefixed with a question mark ? and subsequent parameters are prefixed with an ampersand &.

Signed Authentication Parameters

Some third-party APIs, such as Amazon Web Services and Moz, require a signed authentication parameter to be included in their API query to secure the identity of the user. A signed authentication parameter is comprised of one or more data elements, such as an API key or a user ID, that have been encrypted to produce a unique key.

The data elements required to build the signed authentication parameter are typically specified by the third-party API. This signed authentication parameter is included in the API query following the same syntax as a regular parameter. Klipfolio's Signed Authentication Builder (Hash Helper) provides a set of methods to create this signed authentication parameter.

Example API queries

Below are some examples of what API queries may look like:

Twitter API query

https://api.twitter.com/1.1/followers/list.json

where

<webserviceURL> = https://api.twitter.com
<version> = 1.1
<endpoint> = followers/list
<outputFormat> = json

and Authentication is type OAuth.

Klipfolio API query

https://app.klipfolio.com/api/1.0/datasources

where

<webserviceURL> = https://app.klipfolio.com/api
<version> = 1.0
<endpoint> = datasources

and Query Parameters

<ParameterName> = kf-api-key
<ParameterValue> = <your api key>
<ParameterType> = header

Supported query methods

Klipfolio supports the GET and POST methods for requesting data from an API. The API will specify which method to use. Most APIs use GET, however some APIs use POST for certain queries. Refer to the API documentation of the service you are connecting to for more information.

Creating a REST/URL data source or data feed

If you're working in Klips, you'll create REST/URL data sources.  If you're working in PowerMetrics, you'll create REST/URL data sources or data feeds. Data feeds are being released gradually to PowerMetrics accounts. To see whether this feature is active in your account, check for Data Feeds in the left navigation sidebar.

If you’re creating a REST/URL data source or data feed using the POST method, see this section: Tips for creating a REST/URL data source or data feed using POST.

To create a REST/URL data source or data feed:

  1. To add a new data source: Click the + button beside Data Sources in the left navigation sidebar. On the Where is your data? page, under Additional options (Klips) or Core Services (PowerMetrics), select REST/URL.
  2. To add a new data feed: Click the + button beside Data Feeds in the left navigation sidebar. Click Select data. On the Where is your data? page, under Core Services, select REST/URL.
  3. For data sources and data feeds, on the Configure your data source/service page, fill in the following information:
  • Query URL: enter the API query according to the web service's API specification
  • Data Format: select the output format returned by the API (Excel, CSV, JSON or XML)

Note: This field specifies how the response from the API is parsed and is not necessarily related to the POST request body type. The POST request body type is usually specified as the request header in the Query Parameters section. For more information, see Tips for creating a REST/URL data source or data feed using POST below.

  • Method: select the method required by the API (GET or POST).
  1. Set Query Parameters as required by the API (many APIs do not require any). Type a Name and Value for each parameter required and set one of the following Types:
  • Query - This is equivalent to the parameters in an API query. You can either include them in the URL or in this section.
  • Header - If required by the API (for example, Smartsheets), add parameters to the query Header.
  • Cookie - If required by the API, Cookie parameters are used for session-related data.
  1. Configure the Authentication (if applicable):
  • If the API uses API Key authentication, set Query Parameters according to the API's specification for the API Key parameter and leave Authentication Type set to None.
  • Otherwise, select the Authentication Type and fill in the required fields.
  1. Click Get data, then Continue once the data is verified.
  2. If you added a data source, click Save and name the data source.
  3. If you added a data feed, you're taken to the data feed editor, where you can either make changes to the data feed or save it as-is. If you want to modify the data feed, go to this article for detailed editing information. Give the data feed a name and, optionally, enter a description. Click Save data feed.

The data source or data feed is added to your account and is ready to use for custom Klips or custom metrics. To see a list of all your data sources or data feeds, click either Data Sources or Data Feeds in the left navigation sidebar.

Tips for creating a REST/URL data source or data feed using POST

Service APIs that require a POST request also require you to specify headers.

The most common set of parameters for REST APIs and most GraphQL APIs is as follows:

  • Using POST as the Method where the Body contains JSON data, expand Query Parameters and enter Content-Type as the Name and application/json as the Value. Select Header as the Type.

The most common set of parameters for SOAP APIs is as follows:

  • Using POST as the Method where the Body contains XML data, expand Query Parameters and enter Content-Type as the Name and application/xml as the Value. Select Header as the Type.

See below for an example that uses POST with JSON data:

Creating a GraphQL data source using REST

If you are connecting to GraphQL using REST, follow the REST API connection instructions and enter the following information:

  • At Query URL, ensure your query ends with a GraphQL endpoint. (these usually end in /graphql).
  • At Method, select POST
  • At Body, enter {"query": "<yourStringEscapedGraphQLquery>"}as in the example below:

    Ensure that you escape any strings inside the query using backslashes. If you are having trouble converting your GraphQL query into a string escaped query, you can use an online tool to convert your query for you.
  • Expand Query Parameters and enter Content-Type as the Name and application/json as the Value. Select Header as the Type.

Next steps

Great! You've connected to your data and created one (or more) data sources or data feeds. Now you're ready to use them to create custom Klips or custom metrics.

Updated
Have more questions? Submit a request