Core Functionality

Warning

This page is currently in development.

This page provides instructions and examples around the core functionality of the library. This includes a review of the Basic Usage as well as base functionality such as performing generic API requests.

• Getting Started

  • Importing the package

  • Initializing the modules

  • Establishing the API connection

• Performing GET Requests

  • Using the get_data() function

    • Optional arguments in the get_data() function

      • Ignoring exceptions in the get_data() function

      • Returning the get_data() response in JSON format

  • Using the get_request_with_retries() function

    • Returning the get_request_with_retries() response in JSON format

• Performing POST Requests

• Performing PUT Requests

Getting Started

The topics in this section are necessary to leverage the khorosjx library.

Importing the package

The package can be imported into a Python script using the syntax below.

import khorosjx

Initializing the modules

While it is certainly possible to import modules directly (e.g. from khorosjx import users), it is recommended that you instead leverage the init_module() function as shown below.

khorosjx.init_module('content', 'users')

In the example above, both the khorosjx.content and the khoros.users modules have been initiated.

Note

It is not necessary to import the khorosjx.core module as it is imported by default.

Establishing the API connection

Before leveraging the API in function calls, you must first establish your connection by providing the base URL for the environment (e.g. https://community.example.com) and the username and password for the unfederated service account through which the API calls will be made. This is demonstrated below.

base_url = 'https://community.example.com'
credentials = ('adminuser', 'password123!')
khorosjx.core.connect(base_url, credentials)

Note

At this time the library only allow connections using basic authentication, but there are plans to include the ability to leverage OAuth 2.0 in a future release.

Once the connection has been established, you can proceed to leverage the library of functions in the various modules as needed.

See also

To facilitate the getting started process, you may want to consider Using the Helper Utility.

Performing GET Requests

There are two primary ways to perform GET requests against the Core API. The first is to use the get_data() function, which avoids the necessity to construct a query URI but is somewhat restrictive in what can be returned. The second is more flexible but does require the construction of API query URIs.

Both of these methods are addressed in the sections below.

Using the get_data() function

The get_data() function performs GET requests by requiring only two arguments: the API endpoint and a lookup value.

The API endpoints, also known as the API services in the Jive REST API documentation, are the different avenues within the API through which data can be retrieved and, in some cases, created and/or modified. The endpoints supported within the khorosjx library are listed below.

abuseReports	acclaim	actions	activities	addOns	announcements
attachments	calendar	checkpoints	collaborations	comments	contents
deletedObjects	dms	events	eventTypes	executeBatch	extprops
extstreamDefs	extstreams	ideaVotes	images	inbox	invites
members	mentions	messages	moderation	oembed	outcomes
pages	people	places	placeTemplateCategories	placeTemplates	placeTopics
profileImages	publications	questions	rsvp	search	sections
securityGroups	shares	slides	stages	statics	streamEntries
streams	tags	tileDefs	tiles	urls	versions
videos	vitals	votes	webhooks

By default, the respective ID is used as the lookup value for each endpoint. For example, when querying the people endpoint the default lookup value is the User ID, whereas when querying the contents endpoint the default lookup value is the Content ID.

The example below shows how you would use the function to retrieve data for content with 12345 as its Content ID.

api_response = khorosjx.core.get_data('contents', 12345)

Note

Because f-strings are leveraged to construct the query URIs in the function, the lookup value can be supplied as an integer or a string.

When querying against specific endpoints, other identifiers may be permitted as well. For example, if querying for user data via the people endpoint it is possible to supply a User ID, username or email address as demonstrated in the examples below.

response_from_id = khorosjx.core.get_data('people', 1234)
response_from_email = khorosjx.core.get_data('people', 'john.doe@example.com', 'email')
response_from_username = khorosjx.core.get_data('people', 'john_doe', 'username')

Optional arguments in the get_data() function

There are two optional arguments that may be supplied within the get_data() function which can be useful in certain circumstances. Both are addressed below.

Ignoring exceptions in the get_data() function

When utilizing the get_data() function multiple times, such as when looping through a list of users, it may be useful to ignore exceptions so that the entire script doesn’t fail if data for a single user cannot be returned successfully. This can be done by setting the ignore_exceptions argument to True in the function arguments, as demonstrated below.

api_response = khorosjx.core.get_data('people', 1234, ignore_exceptions=True)

Leveraging this option will result in failed responses printing an error message and then either returning the API response (which will include a status code other than 200) or an empty JSON string. (See the next section)

Returning the get_data() response in JSON format

Rather than having to convert the API response to JSON in your script, you can do so within the get_data() function by setting the return_json argument to True as shown in the example below.

user_json = khorosjx.core.get_data('people', 1234, return_json=True)

Note

As stated in the previous section, if the ignore_exceptions argument is also set to true then JSON data will still be returned but will simply be empty.

Using the get_request_with_retries() function

If you have a need to perform a less generic GET request then it will likely be better to leverage the get_request_with_retries() function instead of get_data() so that the specific query URI can be supplied.

The get_request_with_retries() function performs the GET query and will retry the operation up to five times to account for any unexpected connection aborts or timeouts, which is known to happen on occasion with the Jive APIs.

This function is demonstrated in the example below.

query_uri = f"{base_url}/people/1234/contents?count=100&startIndex=200&fields=@all"
api_response = khorosjx.core.get_request_with_retries(query_uri)

Note

Notice that the base_url global variable is being utilized above, which was defined when establishing the API connection when getting started above.

Returning the get_request_with_retries() response in JSON format

Similar to the get_data() function, you have the option of returning the response in JSON format by setting the return_json argument to True as shown in the example below.

get_request_json = khorosjx.core.get_request_with_retries(query_uri, return_json=True)

Performing POST Requests

Todo

This section is not yet written but will be at a future date.

Performing PUT Requests

Todo

This section is not yet written but will be at a future date.