Performing Community API Calls¶
Warning
This page is still in progress and sections may be missing or unfinished.
Using the Khoros Python SDK to perform Community API calls is easier than doing so manually with the requests library for several reasons, including:
It is unnecessary to pass the entire URL as the base URL is stored in the
khoros.core.Khoros
object. This means the relative URL passed in functions is generally the same that would be passed to the rest or restadmin FreeMarker directives in components, macros or endpoints.The authorization token (e.g. li-api-session-key) is automatically included in the request header for all API calls.
Errors and exceptions are more intuitive with Khoros-specific messages.
There are three types of API calls that can be made using the khoros.core.Khoros
object:
Note
This guide assumes that the khoros.core.Khoros
object has been instantiated
with the khoros
variable name, as illustrated in the snippet below.
>>> from khoros import Khoros
>>> khoros = Khoros(helper='helper.yml')
Community API v1 calls¶
You can perform
Khoros Community API v1
calls using the methods contained within the
khoros.core.Khoros.V1
class:
Use the
khoros.core.Khoros.V1.get()
method to perform GET requests.Use the
khoros.core.Khoros.V1.post()
method to perform POST requests.Use the
khoros.core.Khoros.V1.search()
method to perform searches using the v1 API.
Performing a v1 GET request¶
When performing a GET request using the Community API v1, you can simply pass the relative URI of the endpoint you wish to query.
Although API v1 responses are in XML format by default, this library converts the responses to JSON format by default, converts the JSON string to a Python dictionary and prunes the response to the value you need so that it is not required to do so manually.
>>> khoros.v1.get('/users/online/count')
{'response': {'status': 'success', 'value': {'type': 'int', '$': 544}}}
However, if you prefer to receive your responses in XML format, you need only pass the keyword
argument return_json=False
in the method call. The response will be a
requests.models.Response object
and including .text
will provide the actual XML response.
>>> response = khoros.v1.get('/users/online/count', return_json=False)
>>> type(response)
<class 'requests.models.Response'>
>>> response
<Response [200]>
>>> response.text
'<response status="success">\n <value type="int">551</value>\n</response>\n'
Performing a v1 POST request¶
Performing Community API v1 POST requests using the library are also very simple, requiring only a relative URI and a dictionary of query parameters and their respective values.
>>> khoros.v1.post('/users/id/216/profiles/name/signature/set',
... {'value': 'Joe Customer, PMP '})
{'response': {'status': 'success'}}
As with the GET requests, the
response will be returned in JSON format by default unless the return_json=False
argument is passed in the method.
>>> khoros.v1.post('/users/id/216/profiles/name/signature/set',
... {'value': 'Joe Customer, PMP'}, return_json=False).text
'<response status="success"/>\n'
Note
In order to avoid exceeding URI limits when passing large query parameters in a POST
request, which would result in responses with 413
or 414
status codes, by
default the query parameters are passed as a URL-encoded string in the message body
rather than in the URI.
However, you can still pass the query parameters in the URI
if desired by passing the keyword argument params_in_uri=True
in the method.
Community API v2 calls¶
The primary benefit introduced with the Khoros Community API v2 is the ability to leverage the Lithium Query Language (LiQL) to perform GET requests.
This Python library provides two options for performing LiQL queries. The first is to
provide the full LiQL query as a string argument using the khoros.core.Khoros.query()
method, and the second is to pass separate arguments for the LiQL elements into the
khoros.core.Khoros.search()
method which constructs the LiQL query for you.
Using LiQL queries and the query method¶
If you are familiar and comfortable with the LiQL syntax then you may prefer to construct your own LiQL queries when performing v2 GET requests.
This can be done by leveraging the khoros.core.Khoros.query()
method in the
core object, as demonstrated below.
>>> query = "SELECT login FROM users WHERE id = '216'"
>>> khoros.query(query)
{'status': 'success', 'message': '', 'http_code': 200,
'data': {'type': 'users', 'list_item_type': 'user', 'size': 1,
'items': [{'type': 'user', 'login': 'joeCustomer'}]}, 'metadata': {}}
Because the Community API v2 returns data in JSON format by default, the same can be said for this library.
Passing search parameters to the search method¶
If you are not very comfortable with LiQL syntax (or just want an easy way to
perform LiQL queries) then you can use the khoros.core.Khoros.search()
method to pass LiQL elements and allow the LiQL query to be constructed for you
behind-the-scenes.
The arguments that can be utilized in the method to construct the LiQL query are listed in the table below.
Argument |
Data Type(s) |
Description |
---|---|---|
|
str, tuple, list, set |
One or more fields to be selected within the SELECT statement (e.g. |
|
str |
The source of the data to use in the FROM statement (e.g. |
|
str, tuple, list, dict, set |
The filters (if any) to use in the WHERE clause (e.g. |
|
str, tuple, set, dict, list |
The field(s) by which to order the response data (optional) |
|
bool |
Defines if the ORDER BY directionality is DESC (default) or ASC |
|
int |
Allows an optional limit to be placed on the response items (ignored by default) |
In addition to the arguments above, you can also utilize the optional arguments below to further customize the request and/or response.
Argument |
Data Type(s) |
Description |
---|---|---|
|
bool |
Setting to |
|
bool |
Defines if the response should be “pretty printed” ( |
|
bool |
Defines if the query should be tracked within LSI, aka Khoros Community
Analytics ( |
|
bool |
Ensures that the API response always returns a |
|
str |
Allows an error code to optionally be supplied for testing purposes (ignored by default) |
|
bool |
Determines if statements (e.g. |
Note
These arguments above are also available in the khoros.core.Khoros.query()
method.
To demonstrate how this method works, let us consider the LiQL query
SELECT login FROM users WHERE id = '216'
that was used in the
example
for the khoros.core.Khoros.query()
method. The code snippet
below shows how the same query could be performed using the
khoros.core.Khoros.search()
method.
>>> khoros.search('login', 'users', 'id = "216"')
{'status': 'success', 'message': '', 'http_code': 200,
'data': {'type': 'users', 'list_item_type': 'user', 'size': 1,
'items': [{'type': 'user', 'login': 'joeCustomer'}]}, 'metadata': {}}
Generic API calls¶
If you need to perform a more generic API call (as opposed to an API call to the
v1 or v2 Community API) for any reason but which still includes the authorization
header automatically, such as to query a custom endpoint, then you can leverage
the base methods below from the khoros.core.Khoros
object.
Performing a GET request¶
The method for making a generic GET request is similar to the
khoros.core.Khoros.V1.get()
method in structure, but with a few key
differences:
You have the ability to leverage an absolute or relative URI.
Query parameters cannot be passed as a Python dictionary and must be included in the URI.
Note
This second item above may change in a future release.
Warning
Also similar to the v1 GET request method, the response attempts to return in
JSON format by default. Therefore, if your custom endpoint (or wherever else is being
queried) is not returning in JSON format then you will need to ensure that the keyword
argument return_json=False
is passed when calling the method. This will result in
the method returning the response as a
requests.models.Response
object instead.
Below are some simple examples of how this method might be used.
>>> khoros.get('/plugins/custom/example/example/hello_world')
{'response': 'Hello World!'}
>>> khoros.get('/plugins/custom/example/example/say_hello?name=John',
... return_json=False).text
'Hello, John!'
Note
You may notice that relative URIs are expected by default. If you wish to supply an
absolute URI then you will need to pass the keyword argument relative_url=False
when calling the method.
Performing a POST request¶
Todo
Coming soon!
Performing a PUT request¶
Todo
Coming soon!