Developer Blog Series: An In-Depth Guide To Ratings Using SKY API

Ratings are among the most complex entities that the Constituent API surfaces. The complexities include optionally required fields, value fields that are dynamic based on the data type, and categories that may or may not include a source. So I’ve put together an in-depth guide to ratings and their intricacies.

When dealing with ratings, the first thing you need to know is how sources and categories work. Categories sometimes contain sources, and when they do, API calls must include the source along with the category.

The following example shows a rating category with a source:

Because this rating is type “codetable,” to create a rating with this category, you must first get its possible values through the /rating/category/values endpoint. A call to the values endpoint requires the category_name as a query string parameter. And since the category has a source, the call also must provide the source_name parameter in the query string, resulting in the following call:

GET /ratings/categories/values?category_name=Acquaintance&source_name=Blackbaud%20Analytics%27%20Giving%20Score

This call returns the following response:

Although the example response returns only one option, if more options were available, the response would return them as well.

After completing these initial steps, a call to create a rating is pretty straightforward. You provide the category, source if applicable, and value for the rating category, along with the required type, date, and constituent_id fields.

Now that I’ve gone through the basics of ratings, I’ll show them in practice using our sample Barkbaud app.

The basic premise for Barkbaud is an animal shelter partner app for Raiser’s Edge NXT that provides information about dogs who are available for adoption. To incorporate ratings, I created a tile with full CRUD operations that applies ratings to the behavior and training of the dogs. Since the code is all open source, I only cover a few key features on the ratings tile.

The first thing to note is the functionality of the add behavior/training form.

When a user selects a source, the category field is cleared and the list of available categories is refreshed because not all categories are compatible with all sources. The list of available categories only includes categories associated with the selected source. To find the categories that work with a source, you can call the rating categories endpoint and pass in the source_name as a query string parameter. If you aren’t using a source, pass an empty string to the categories endpoint. For example, we can make the following call:

GET /ratings/categories?source_name=Blackbaud%20Analytics%27%20Giving%20Score

The call returns the following collection:

Since the source_name dictates the available categories, I put logic into the app to refresh the category field when the source field changes.

I also disabled the value field on the add form until the user selects a category. This lets me customize the input for the value field based on the type of the category.

The final thing to mention in the Barkbaud app is the edit form. Only the comment, date, and value properties are editable on ratings, and since I don’t surface the comment or date in the Barkbaud application, I disabled all fields in the edit form except for the value field. To edit, I also take advantage of PATCH and only pass in the value property on the request.

I hope this explains the intricacies of ratings and that it helps develop some really great applications. Be sure to keep an eye the changelog for exciting new endpoints. Happy coding!