Community iOS SDK API reference

The li-ios-sdk package includes API providers and utility methods. This guide provides reference information for the APIs.

• About the providers
• Provider index
• About the data models
• Using the API providers
• Creating custom API providers

About the providers

When using the Community iOS SDK, you can use our out-of-the-box user interface provided by the li-ios-sdk-ui library or you can build your own Community integration.

To help you build your own Community experience, we supply a set of API providers. These providers bundle lower-level APIs along with additional logic to get and set data in Community. The providers themselves do not supply user interface devices; they are convenience methods to support your app development.

All provider calls are on LiClient. You'll access them from LiClientManager.

The providers fall into the following general categories:

• Category and Board providers
• Search providers
• User providers
• Message providers
• Message Action providers

Each provider returns a data model. The models provide GET and POST calls to use the data returned from the provider.

Our API providers are designed to meet the general needs of a Community integration. If our API providers don't meet your needs, you can create your own using our custom API providers, which provide the flexibility of using custom LiQL queries and request bodies. Our API providers support the blog and forum conversation styles.

Note: All providers respect the permissions assigned to the user in context based on their role(s) in Community.

Building the client request

Almost every client requires a set of parameters. Each time you call a client, you first build your parameters by instantiating a parameter object specific to the provider you want to use. Every parameter object can throw an error (LiError.invalidArgument(errorMessage: String)) if invalid parameters are passed to the object, so make sure you wrap the initalization in a try catch block. Then, you build the client request using LiSDKManager.shared().liClientManager.request, calling the desired provider method and passing the parameters as requestParams.

For example, our liCategoryBoardsClient provider retrieves all boards in a given category. It uses LiCategoryBoardsClientRequestParams to build and pass the required parameters.

We build the parameters like this:

do {
    let requestParams = try LiCategoryBoardsClientRequestParams(categoryId: category)
} catch LiError.invalidArgument(let errorMessage) {
    //Handle error
}

Then, we build the client request like this using the liCategoryBoardsClient provider:

LiSDKManager.shared().liClientManager.request(client: .liCategoryBoardsClient(requestParams: requestParams)

Provider index

Below is the list of API general providers included with the Community iOS SDK core package, including descriptions of the providers and the data model each returns. See Creating custom API providers for details about our custom providers.

• Category and Board providers
  • liCategoryBoardsClient(requestParams: LiCategoryBoardsClientRequestParams)
  • liCategoryClient
  • liBoardsByDepthClient(requestParams: LiBoardsByDepthClientRequestParams)
  • liSearchClient(requestParams: LiSearchClientRequestParams)
• User providers
  • liCreateUserClient(requestParams: LiCreateUserClientRequestParams)
  • liUpdateUserClient(requestParams: LiUpdateUserClientRequestParams)
  • liUserDetailsClient(requestParams: LiUserDetailsClientRequestParams)
  • liUserMessagesClient(requestParams: LiUserMessagesClientRequestParams)
  • liUserSubscriptionsClient
• Message providers
  • liMessageClient(requestParams: LiMessageClientRequestParams)
  • liMessagesClient
  • liMessagesByBoardIdClient(requestParams: LiMessagesByBoardIdClientRequestParams)
  • liFloatedMessagesClient(requestParams: LiFloatedMessagesClientRequestParams)
  • liRepliesClient(requestParams: LiRepliesClientRequestParams)
  • liMessagesByIdsClient(requestParams: LiMessagesByIdsClientRequestParams)
• Message Action providers
  • liMessageDeleteClient(requestParams: LiMessageDeleteClientRequestParams)
  • liAcceptSolutionClient(requestParams: LiAcceptSolutionClientRequestParams)
  • liCreateMessageClient(requestParams: LiCreateMessageClientRequestParams)
  • liCreateReplyClient(requestParams: LiCreateReplyClientRequestParams)
  • liKudoClient(requestParams: LiKudoClientRequestParams)
  • liReportAbuseClient(requestParams: LiReportAbuseClientRequestParams)
  • liMarkMessagePostClient(requestParams: LiMarkMessagePostClientRequestParams)
  • liMarkMessagesPostClient(requestParams: LiMarkMessagesPostClientRequestParams)
  • liMarkTopicPostClient(requestParams: LiMarkTopicPostClientRequestParams)
  • liSubscriptionPostClient(requestParams: LiSubscriptionPostClientRequestParams)
  • liSubscriptionDeleteClient(requestParams: LiSubscriptionDeleteClientRequestParams)
  • liUpdateMessageClient(requestParams: LiUpdateMessageClientRequestParams)
  • liUploadImageClient(requestParams: LiUploadImageClientRequestParams)
• Custom providers
  • liGenericDeleteClient( requestParams: LiGenericDeleteClientRequestParams)
  • liGenericPostClient(requestParams: LiGenericPostClientRequestParams)
  • liGenericPutClient(requestParams: LiGenericPutClientRequestParams)
  • liGenericGetClient(requestParams: LiGenericLiqlClientRequestParams)

Category and Board providers

liCategoryBoardsClient(requestParams: LiCategoryBoardsClientRequestParams)

Fetches a list of boards for a given category, along with board and category details.

Create request parameters with LiCategoryBoardsClientRequestParams, passing the categoryId of the category from which to fetch the boards.

Returns [LiBrowse]

liCategoryClient

Fetches category details available to the current user. It selects from nodes where node_type is equal to a category. This method respects the Hide from Lists and Menus settings in Community Admin.

This provider takes no parameters.

Returns [LiBrowse]

liBoardsByDepthClient(requestParams: LiBoardsByDepthClientRequestParams)

Fetches boards at a specific depth in the Community Structure hierarchy.

Create parameters with LiBoardsByDepthClientRequestParams(depth: Int). Takes depth as a parameter.

Returns [LiBrowse]

Search providers

liSearchClient(requestParams: LiSearchClientRequestParams)

Performs a keyword search in Community.

Create request parameters with LiSearchClientRequestParams(query: String). Takes the search text (passed as query), where query is compared against the body and subject of the message.

Returns [LiMessage]

User providers

liCreateUserClient(requestParams: LiCreateUserClientRequestParams)

Creates a new user account. Create parameters with LiCreateUserClientRequestParams(email: String, firstName: String?, lastName: String?, login: String, password: String, avatarUrl: String?, avatarImageId: String?, avatarExternal: String?, avatarInternal: String?, biography: String?, coverImage: String?).

• email of the user.
• firstName of the user. (optional)
• lastName of the user. (optional)
• login username for the user.
• password password for the account.
• avatarUrl image url for user profile. (optional)
• avatarImageId of the image uploaded for the user. (optional)
• avatarExternal for the user profile. (optional)
• avatarInternal for the user profile. (optional)
• biography for the user. (optional)
• coverImage for the user profile. (optional)

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liUpdateUserClient(requestParams: LiUpdateUserClientRequestParams)

Updates an existing user. Create parameters with LiUpdateUserClientRequestParams(id: String, email: String?, firstName: String?, lastName: String?, login: String?, avatarUrl: String?, avatarImageId: String?, avatarExternal: String?, avatarInternal: String?, biography: String?, coverImage: String?).

• id of the user
• email of the user. (optional)
• firstName of the user. (optional)
• lastName of the user. (optional)
• login username for the user. (optional)
• avatarUrl image url for user profile. (optional)
• avatarImageId of the image uploaded for the user. (optional)
• avatarExternal for the user profile. (optional)
• avatarInternal for the user profile. (optional)
• biography for the user. (optional)
• coverImage for the user profile. (optional)

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liUserDetailsClient(requestParams: LiUserDetailsClientRequestParams)

Fetches details about the specified user.

Create request parameters with LiUserDetailsClientRequestParams(userId: String). Takes userId as a parameter.

Returns [LiUser] with the details at index 0 of the array.

liUserMessagesClient(requestParams: LiUserMessagesClientRequestParams)

Fetches blog and forum messages posted by the specified author up to a specified depth. Depth is the location of the message in the thread where 0 equals the topic message, 1 is a first-level reply, and so on.

Create request parameters with LiUserMessagesClientRequestParams(authorId: String, depth: Int). Takes authorId and depth as parameters.

Both blog and forum messages are returned by default unless you have limited the discussion styles supported in your Community iOS SDK instance to a single discussion style in Community Style > System > API Apps.

Returns [LiMessage]

liUserSubscriptionsClient

Fetches a list of all Community subscriptions set by the current user.

This provider does not take any parameters.

Returns [LiSubscriptions]

Message providers

liMessageClient(requestParams: LiMessageClientRequestParams)

Fetches a specific message for the user in context.

Create parameters with LiMessageClientRequestParams(messageId: String).

Returns [LiMessage] with the details at index 0 of the array.

liMessagesClient

Fetches a list of all the messages for the user in context.

This provider takes no parameters.

Returns [LiMessage]

liMessagesByBoardIdClient(LiMessagesByBoardIdClientRequestParams)

Fetches all messages on to the specified board.

Create parameters with LiMessagesByBoardIdClientRequestParams(boardId: String). Takes boardId as a parameter.

Returns [LiMessage]

liFloatedMessagesClient(requestParams: LiFloatedMessagesClientRequestParams)

Fetches all messages floated (or "pinned") to the top of the specified board.

Create parameters with LiFloatedMessagesClientRequestParams(boardId: String, scope: String). Takes boardId and scope as parameters.

Supported value for scope is local. It retrieves messages that the current user has floated to the top of the specified board, rather than an administrator who might have pinned a message to the top of a board globally for the community.

Returns [LiFloatedMessage]

liRepliesClient(requestParams: LiRepliesClientRequestParams)

Fetches details of child messages (replies or comments, and nested replies and comments) of the specified parent message.

Create parameters with LiRepliesClientRequestParams(parentId: String, limit: Int, offset: Int). Pass the following:

• parentId - Id of the message.
• limit - Number of items to fetch at once.
• offset - Number of items to skip before returning data. The default value is 0.

A combination of limit and offset can be used to retrieve replies in a paginated manner.

Returns [LiMessage]

liMessagesByIdsClient(requestParams: LiMessagesByIdsClientRequestParams)

Fetches details for the specified message.

Create parameters with LiMessagesByIdsClientRequestParams(messageIds: [String]). Takes messageIds as a parameter. Pass the message IDs as an array of Strings.

Returns [LiMessage]

Message Action providers

liMessageDeleteClient(requestParams: LiMessageDeleteClientRequestParams)

Deletes the specified message.

Creates parameters with LiMessageDeleteClientRequestParams(messageId: String, includeReplies: Bool). Takes messageId and includeReplies as parameters.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liAcceptSolutionClient(requestParams: LiAcceptSolutionClientRequestParams)

Marks the specified message as an accepted solution on behalf of the current user.

Create parameters with LiAcceptSolutionClientRequestParams(messageId: String). Takes the messageId of the message to accept as a solution as a parameter.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liCreateMessageClient(requestParams: LiCreateMessageClientRequestParams)

Creates a new message.

Create parameters with LiCreateMessageClientRequestParams(subject: String, body: String?, boardId: String, imageId: String?, imageName: String?).

Pass the following:

• subject of the message.
• body of the message. (optional)
• boardId of the board in which to post the message.
• imageId if the message contains an image. (optional)
• imageName if the message contains an image. (optional)

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liCreateReplyClient(requestParams: LiCreateReplyClientRequestParams)

Creates a reply to a message.

Create parameters with LiCreateReplyClientRequestParams(body: String, messageId, subject: String, imageId: String?, imageName: String?).

Pass the following:

• subject of the message.
• body of the message.
• messageId of the parent message of this reply.
• imageId if the message contains an image. (optional)
• imageName if the message contains an image. (optional)

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liKudoClient(requestParams: LiKudoClientRequestParams)

Kudos the specified message on behalf of the current user.

Create parameters with LiKudoClientRequestParams(messageId: String). Takes messageId of the message to kudo as a parameter.

Returns [LiMessage] with the details at index 0 of the array.

liReportAbuseClient(requestParams: LiReportAbuseClientRequestParams)

Creates an abuse report on the specified message.

Create parameters with LiReportAbuseClientRequestParams(messageId: String, userId: String, body: String). Takes messageId, userId of the user reporting abuse, and body of the message being reported as parameters.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liMarkMessagePostClient(requestParams: LiMarkMessagePostClientRequestParams)

Mark a single message as read or unread.

Create parameters with LiMarkMessagePostClientRequestParams(userId: String, messageId: String, markUnread: Bool). Takes userId, messageId and markUnread as parameters.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liMarkMessagesPostClient(requestParams: LiMarkMessagesPostClientRequestParams)

Marks a set of messages (not necessarily in the same thread) as read or unread. Compare this to liMarkTopicPostClient(requestParams: LiMarkTopicPostClientRequestParams).

Create parameters with LiMarkMessagesPostClientRequestParams(userId: String, messageIds: [String], markUnread: Bool). Pass messageIds as a array of String.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liMarkTopicPostClient(requestParams: LiMarkTopicPostClientRequestParams)

Marks a topic message and all its replies as read or unread. Compare this to liMarkMessagesPostClient(requestParams: LiMarkMessagesPostClientRequestParams), which marks individual messages (not necessarily in the same thread) as read or unread.

Create parameters with LiMarkTopicPostClientRequestParams(userId: String, topicId: String, markUnread: Bool). Takes userId, topicId, and markUnread as parameters.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liSubscriptionPostClient(requestParams: LiSubscriptionPostClientRequestParams)

Create a subscription to the specificed target.

Create parameters with LiSubscriptionPostClientRequestParams(targetId: String, targetType: String).

Pass the following:

• targetId- ID of the subscription target (either a message ID or board ID)
• targetType - message or board

Returns [LiSubscriptions] with the details at index 0 of the array.

liSubscriptionDeleteClient(requestParams: LiSubscriptionDeleteClientRequestParams)

Deletes a subscription.

Create parameters with LiSubscriptionDeleteClientRequestParams(subscriptionId: String). Pass the subscriptionId of the subscription to delete.

returns [LiGenericQueryResponse] with the details at index 0 of the array. Which contains the data in the form of [String: Any].

liUnKudoClient(requestParams: LiUnKudoClientRequestParams)

Removes kudos on the specified message on behalf of the current user. Create parameters with LiUnKudoClientRequestParams(messageId: String). Takes messageId as a parameter. Pass the messageId of the message to unkudo.

Returns [LiMessage] with the details at index 0 of the array.

liUpdateMessageClient(requestParams: LiUpdateMessageClientRequestParams)

Updates the specified message.

Create parameters with LiUpdateMessageClientRequestParams(messageId: String, subject: String, body: String?, imageId: String?, imageName: String?).

Pass the following:

• messageId of the message to update.
• subject of the message.
• body of the message. (optional)
• imageId if the message contains an image. (optional)
• imageName if the message contains an image. (optional)

Returns [LiMessage] with the details at index 0 of the array.

liUploadImageClient(requestParams: LiUploadImageClientRequestParams)

Uploads an image to Community on behalf of the current user into the user's public album.

Create parameters with LiUploadImageClientRequestParams(title: String, description: String, imageName: String, image: UIImage).

Pass the following:

• description of the image
• display title of the image
• imageName of the file to upload
• UIImage object to upload

returns [LiImageResponse] with the details at index 0. The response contains the reference id of the uploaded image in the community.

About the data models

For GET requests provided by the general API providers, there are pre-defined data models for getting the data. Below are the details of different models:

GET Models

Model	Description
LiFloatedMessageModel	This model maps to 'floated_message'. It is used to store information of pinned messages. liFloatedMessagesClient uses this model.
LiMessage	This model maps to the Community API v2 message resource in Community. This model is used for retrieving messages and message details, and keyword searches. liSearchClient, liUserMessagesClient, liMessageClient, liRepliesClient, and liMessagesByIdsClient use this model.
LiSubscriptions	This model maps to the Community API v2 subscriptions resource in Community. This is used to store details of all the messages a user is subscribed to. liUserSubscriptionsClient uses this model.
LiUser	This model maps to the Community API v2 users resource in Community. It is used to store all details of a user. liUserDetailsClient uses this model.
LiUserContext	This model maps to the Community API v2 user_context resource. It stores information regarding user permissions, such as whether a user can read messages, reply to messages, kudo messages, and accept a message as a solution. This model is not used directly by any of the iOS SDK Core clients.

Using the API providers

Our providers are initialized using LiSDKManager.shared().clientManager.

Here are examples of calling liMessagesClient.

LiSDKManager.shared().clientManager.request(client: .liMessagesClient, completionHandler: { (result: Result<[LiMessage]>) in
    switch result {
    case .success(let data):
        //update the UI to display the messages
    case .failure(let error):
        //show an error message and handle the error.
    }
})

Creating custom API providers

We have custom GET, PUT, DELETE and POST providers for when you need the freedom to use custom LIQL queries (when using GET) and custom request bodies (when using POST, DELETE and PUT). In the API, the term generic is synonymous with custom. The custom API providers are not dependent on specific models, as is the case for the API providers. All generic providers can be mapped to [LiGenericQueryResponse].

liGenericDeleteClient( requestParams: LiGenericDeleteClientRequestParams)

Create parameters with LiGenericDeleteClientRequestParams(liQueryRequestParams: [String: String]?, id: String, collectionsType: LiClientManager.CollectionsType, subResourcePath: String?)

This is a generic DELETE client which takes the following parameters:

• liQueryRequestParams - (optional) query parameters for the delete query.
• id - the ID of the item being deleted.
• collectionsType - the collection type of the item being deleted. Supported values: messages or subscriptions
• subResourcePath - (optional) This parameter is appended after id in the URL.

The following example deletes a message

// Build the client request parameters
let requestParams = LiGenericDeleteClientRequestParams(liQueryRequestParams: nil, id: "447", collectionsType: LiClientManager.CollectionsType.messages, subResourcePath: nil)

LiSDKManager.shared().clientManager.request(client: .liGenericDeleteClient(requestParams: liClientRequestParams), completionHandler: { (result: Result<[LiGenericQueryResponse]>) in
    switch result {
    case .success(let data):
        //Do something on success.
    case .failure(let error):
        //Do something if the request fails.
    }
})

liGenericPostClient(requestParams: LiGenericPostClientRequestParams)

Create parameters with LiGenericPostClientRequestParams(path: String, requestBody: [String: Any], additionalHttpHeaders: [String: String]?).

This is a generic POST client which takes the following parameters:

• path - (required) path of a Community API v1 or v2 endpoint as a String. Begin path after /community/2.0/<tenant_ID>/. The rest of the endpoint path is generated automatically. For example, to use the endpoint /community/2.0/<tenant_id>/messages, pass "messages"
• requestBody - (required) a String object representing the request body
• additionalHttpHeaders - (optional) a String object representing any additional HTTP headers

The following example posts a new message using the /messages endpoint.

// Build the request body and add message body, type, and ID properties
let requestBody: [String: Any] = ["body": "this is test reply", "type": "message", "id": "820"]
 
// Add any additional HTTP headers if needed. This is optional.
let additionalHttpHeaders: [String: String] = ["APIVersion": "1.0.1"] 
// Build the client request parameters
// Pass the /messages endpoint , the requestBody and the additionalHttpHeaders created earlier.
let liClientRequestParams = LiGenericPostClientRequestParams(path: "/messages", requestBody: requestBody, additionalHttpHeaders: additionalHttpHeaders)

LiSDKManager.shared().clientManager.request(client: .liGenericPostClient(requestParams: liClientRequestParams), completionHandler: { (result: Result<[LiGenericQueryResponse]>) in
    switch result {
    case .success(let data):
        //Do something on success.
    case .failure(let error):
        //Do something if the request fails.
    }
})

liGenericPutClient(requestParams: LiGenericPutClientRequestParams)

Create parameters with LiGenericPutClientRequestParams(path: String, requestBody: [String: Any], additionalHttpHeaders: [String: String]?)

This is a generic PUT client which takes the following parameters:

• path - (required) path of a Community API v1 or v2 endpoint as a String. Begin path after /community/2.0/<tenant_ID>/. The rest of the endpoint path is generated automatically. For example, to use the endpoint /community/2.0/<tenant_id>/messages, pass "messages"
• requestBody - (required) a String object representing the request body
• additionalHttpHeaders - (optional) a String object representing any additional HTTP headers

The following example updates an existing message using the /messages endpoint.

// Build the request body and add message body, type, and ID properties
let requestBody: [String: Any] = ["body": "This is an edited reply body", "type": "message", "id": "820"]
// Build the client request parameters
// Pass the /messages endpoint and the requestBody created earlier
let liClientRequestParams =  LiGenericPutClientRequestParams(path: "/messages", requestBody: requestBody, additionalHttpHeaders: nil)

LiSDKManager.shared().clientManager.request(client: .liGenericPutClient(requestParams: liClientRequestParams), completionHandler: { (result: Result<[LiGenericQueryResponse]>) in
    switch result {
    case .success(let data):
        //Do something on success.
    case .failure(let error):
        //Do something if the request fails.
    }
})

liGenericGetClient(requestParams: LiGenericClientRequestParams)

Makes a LiQL query and returns data in the form of a dictionary [String: Any] as part of the LiGenericQueryResponse model.

Create parameters with LiGenericClientRequestParams(liQuery: String). Takes liQuery as a parameter, where liQuery is a LiQL query (E.g., "SELECT subject, body FROM messages LIMIT 1")

This example uses a custom GET provider to fetch messages by topic IDs.

// Create the LiQL query
let newReplyQuery = "SELECT id, user_context.read, parent.id FROM messages WHERE parent.id in ('830', '805')";
  
// Build the client request parameters
// Create the custom provider client
let liClientRequestParams = LiGenericLiqlClientRequestParams(liQuery: newReplyQuery)

LiSDKManager.shared().clientManager.request(client: .liGenericGetClient(requestParams: liClientRequestParams), completionHandler: { (result: Result<[LiGenericQueryResponse]>) in
    switch result {
    case .success(let data):
        //Do something on success.
    case .failure(let error):
        //Do something if the request fails.
    }
})