In Klipfolio, a web accessible resource is used to access data from a web service, such as Twitter or LinkedIn, through a defined Application Programming Interface (API). The internet is home to thousands of web service APIs and Klipfolio's web accessible resource can be used to connect to most APIs that use the REST (REpresentational State Transfer) protocol and one of the following authentication methods (if authentication is required): OAuth authentication.
NOTE: REST APIs with additional authentication requirements, such as an initial login request, may not be accessible using Klipfolio's web accessible resource.
How to read an API query
Each web service API has its own unique definition and requirements, and it is necessary to refer to the web service API documentation for specific details:
- 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)
- 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, epoch)
- 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:
A REST-based query may not include all elements shown. If the query includes parameters, the first parameter is prefixed with a question mark (?) and subsequent parameters are prefixed with and 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 making the API query. 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. Klipfolio's Signed Authentication Builder (Hash Helper) provides a set of methods to create this signed authentication parameter. The data elements required to build the signed authentication parameter are specified by the third-party API. This signed authentication parameter is included in the API query following the same syntax as a regular parameter.
Yahoo Weather API query
<webserviceURL> = http://weather.yahooapis.com
<endpoint> = forecastrss
<parameter1Name> = w
<parameter1Value> = 3369
<parameter2Name> = u
<parameter2Value> = c
Twitter API query
<webserviceURL> = https://api.twitter.com
<version> = 1.1
<endpoint> = followers/list
<outputFormat> = json
Klipfolio supports the GET and POST methods for requesting data from an API. The API will specify which method to use and most use GET, although certain APIs, such as Infusionsoft, require POST.
How to create a web accessible resource
In Klipfolio, to create a web accessible resource:
- Go to the Library and select the Data Sources tab.
- Click Create a New Data Source and select Web Accessible Resource.
- On the screen presented, fill in the required information:
- URL: type the API query according to the web service's API specification
- Format: select the output format returned by the API (Excel, CSV, JSON or XML)
- Method: select the method required by the API (GET or POST).
- 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.
Be sure the date format in the query matches that required by the API. For more information, refer to date range values.