Design Philosophy

This API wrapper tries to generalize the API calls. First we must find out the generalization in API URL structure.

Klout API URL Structure

Klout’s API URL structure is RESTful with a little cutomization. Almost all API URLs can be generalized in a way.

<protocol>://<domain>/<version>/<resource>.<format>/<input_name>/<input_value>/<action>?<query_string>

• <protocol>: http or https
• <domain>: api.klout.com
• <version>: v2 for the new API
• <resource>: Currently there are only 2 resources identity and user
• <format>: Klout no longer supports XML. Only json is supported.
• <input_name>: (Optional) Name of the field to query. Required only when the input field is not Primary Key. Possible values for identity resource are:
  • tw - Twitter
  • klout - (Written as ks in official Klout API documentation but it doesn’t work)
  • gp - Google+
  • twitter (when using twitter screenName as input)
• <input_value>: Valule of the <input_name> specified. Can be twitter id, google plus id or klout id.
• <action>: Name of the action to be performed.
• <query_string>: Must contain a key obtained from <http://klout.com/s/developers/v2>. MUST also contain screenName when <input_name> is twitter

Note

<input_name> MUST be skipped when query a resource with Primary Key e.g. when call user resource with kloutId, the <input_name> should be skipped.

Note

<input_value> MUST be skipped when <input_name> is twitter The value should be passed in <query_string> instead.

Note

<action> MUST be skipped when expected result is Primary Key e.g. when call identity resource and expected result is kloutId

Designing python functions

After generalizing the API URLs, next step is to make a generalized pythonic function calls:

Here is what I propose:

k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
k.<resource>.<action>(<input_name>=<input_value>)

Klout API URL to Python Function mapping examples

Here are all possible combinations of the URLs. Lets try to map them to our generalized structure defined above:

• http://api.klout.com/v2/identity.json/gp/112975106809988327760?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: http
  • domain: api.klout.com
  • version: v2
  • resource: identity
  • format: json
  • input_name: gp - Google+
  • input_value: 112975106809988327760 - Google+ Id
  • action: Empty - We need kloutId as output
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.identity.klout(gp='112975106809988327760')
  # Note that we replaced the empty action with klout as we want to be consistent
  

• http://api.klout.com/v2/identity.json/tw/11158872?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: http
  • domain: api.klout.com
  • version: v2
  • resource: identity
  • format: json
  • input_name: tw - Twitter
  • input_value: 11158872 - Twitter Id
  • action: Empty - We need kloutId as output
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.identity.klout(tw='11158872')
  # Note that we replaced the empty action with klout as we want to be consistent
  

• http://api.klout.com/v2/identity.json/twitter?key=xxxxxxxxxxxxxxxxxxxxxxxx&screenName=erfaan

  • protocol: http
  • domain: api.klout.com
  • version: v2
  • resource: identity
  • format: json
  • input_name: twitter
  • input_value: Empty - We want to query using twitter screenName
  • action: Empty - We need kloutId as output
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx&screenName=erfaan - screenName is only required in this case

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.identity.klout(screenName='erfaan')
  # Note that we replaced the empty action with klout as we want to be consistent
  # Also the input parameters query string are used as function parameters. (again consistency)
  

• http://api.klout.com/v2/identity.json/klout/11747/gp?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: http
  • domain: api.klout.com
  • version: v2
  • resource: identity
  • format: json
  • input_name: klout
  • input_value: 11747
  • action: gp - Google+
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.identity.gp(klout='11747')
  

• http://api.klout.com/v2/identity.json/klout/11747/tw?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: http
  • domain: api.klout.com
  • version: v2
  • resource: identity
  • format: json
  • input_name: klout
  • input_value: 11747
  • action: tw - Twitter
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.identity.tw(klout='11747')
  

• https://api.klout.com/v2/user.json/11747/score?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: https
  • domain: api.klout.com
  • version: v2
  • resource: user
  • format: json
  • input_name: Empty - We are inputting kloutId
  • input_value: 11747
  • action: score
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.user.scrore(kloutId='11747')
  

• https://api.klout.com/v2/user.json/11747/influence?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: https
  • domain: api.klout.com
  • version: v2
  • resource: user
  • format: json
  • input_name: Empty - We are inputting kloutId
  • input_value: 11747
  • action: influence
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.user.influence(kloutId='11747')
  

• https://api.klout.com/v2/user.json/11747/topics?key=xxxxxxxxxxxxxxxxxxxxxxxx

  • protocol: https
  • domain: api.klout.com
  • version: v2
  • resource: user
  • format: json
  • input_name: Empty - We are inputting kloutId
  • input_value: 11747
  • action: topics
  • query_string: key=xxxxxxxxxxxxxxxxxxxxxxxx

  Code Example:

  k = Klout(key='xxxxxxxxxxxxxxxxxxxxxxxx')
  k.user.topics(kloutId='11747')