We ♥ Our API

Over the last few months we here have been working hard on a handful of exciting projects which are built on top of our own REST API. We’ve made great strides and are looking forward to releasing these products sometime soon, but the byproducts of these efforts — namely, a number of modest enhancements that bring our API closer to parity with our web application — are available now and should prove handy to anyone building a third-party application against our service.

Here is a quick overview of some of the API improvements we’ve just released.

Support for Comma-Separated Values in a Topic Filter

GET requests to /companies/company_id_or_domain/topics now support comma-separated values for these query string parameters:

product

user_defined_code

status

By default, when a multi-value product filter is provided, the topics returned will include only those topics associated with a product that matches ANY product mentioned in the filter list. If the additional query string name-value pair product_match=all is provided, then the topics returned will include only those topics that have associations with ALL products mentioned in the filter list.

should return only those topics that are associated to both the Karel the Robot product and the Solitaire product in the Hello World community.

The analogous is true for the user_defined_code and user_defined_code_match query string parameters. In addition, for the sake of convenience, shorter aliases for these query string parameters have been introduced: udc and udc_match, respectively.

Likewise, the status filter accepts a comma-separated list of valid status values — i.e., complete, rejected, pending, active, and none. Note that there is no “match all” mode for the status filter parameter. This filter only supports the “match any” mode. This is because it is impossible for a topic to have more than one status value.

Associated Products for a Topic

For GET requests to endpoints ending in /topic/topic_id_or_slug, the response JSON payload now includes an array nested under products. It also now includes the product_count integer value.

The product list is ordered alphabetically by name, and it is limited to the first 30 products.

If the API client wants to get more than the first 30 products associated to the topic, the client can make a follow-up call to /topics/topic_id_or_slug/products?page=2&limit=30&sort=alpha. The API client may then continue to make follow-up calls, incrementing the page value each time, until the full list of products has been retrieved.

The API client can determine whether it should make the follow-up call to get more associated products by checking whether product_count is greater than the length of the products array.

User-Specific Topic/Reply Data for Authenticated Users

If an API client is making requests as an authenticated user and the API client makes a call to an endpoint that ends in /topics/topic_id_or_slug, the topic response payload will now indicate whether the authenticated user is following the topic in question and whether the authenticated user has me-tooed the topic in question.

Similarly, if an API client making requests as an authenticated user makes a call for an individual reply or a list of replies, each reply in the response payload will indicate whether the authenticated user has starred the reply in question.

Sorting Topic Search Results and Sorting by Topic Activity

It used to be that if you performed a full-text search on topics and tried to sort the results by making an API call like the following:

GET /companies/hello_world/topics?query=robot&sort=most_replies

the results you received would not respect the specified sort order. Instead the results were returned according to the built-in relevance ranking of our search indexer. In the latest release of the API, however, results for full-text searches on topics are ordered according to the user-specified sort parameter.

What’s more, we’ve introduced a new sort parameter option for topics: most_activity. So the following request:

GET /companies/hello_world/topics?sort=most_activity

will order its results by activity in descending order — where activity is the measured by the sum of a topic’s me-toos and replies.

These changes to the API are varied and fairly disparate, but we hope that together they make it even easier and more compelling for outside developers to leverage the strengths of the Get Satisfaction platform.