State vs. Statements – Rustici Software Knowledge Base

Brad writes:

Hi guys,

If you are still feeling magnanimous I’ve got another question for you to ponder.

I’m trying to make the adjustment from my old SCORM mentality to xAPI and figuring out what to store where and I wonder if you’d mind if I run my thoughts past you once and get your input.

At the minimum I’m doing an “experienced” for each page of a course that is visited and I suppose I could deduce bookmark data by that but instead I’m using the State API to store a JSON object that I can quickly get a bookmark string and last page visited or other misc. data from. From what I gather this is probably pretty standard so far.

But now I’m hooking up a little five-star rating system to each page so the user will be able to rate them. Do you have any opinions on where is the best place to store that? I suppose that if they are changing the rating for some reason we’d like to know that, in which case I’d use a regular statement API call, otherwise the State API? Let’s just hypothetically suppose that this was going to be a one-time storage though…possibly in the case where the user is not allowed to change their selection. Would you still use the Statement API?

My understanding is that the Statement APIs leave a permanent breadcrumb trail that never gets deleted, whereas the State API gets overwritten with the new data. Are there any advantages/disadvantages of using the one over the other except for the breadcrumb trail?

Best!

Brad

My response:

Reading your question and explanations, I feel like you know the right answer. You're exactly right that Statements are used to provide a journal (or stream!) of activity whereas the State API is over-writable data storage for things like bookmarking. Here's some more advantages/disadvantages of the State API vs. the Statement API (flip these round for the advantages and disadvantages of Statements!)

Freedom of data structure; the Statement API restricts the structure of what you send.
Can contain any type of document, not just JSON
Possibly less storage requirements if old records are not kept
Can be easier to pull data from; aggregating data from many statements can be difficult.
Not interoperable. Don't expect other tools (like Watershed) to read data from the State API without some custom development; they might be able to do interesting things with your Statements out of the box.
Less visible to learners e.g. if the learner has their own activity stream view.

Based on the above, I don't think there's a right or wrong answer for this scenario, at least from the information you've presented. Personally I'd be inclined to use Statements as it seems like this data could be used for journalling later, even if that's not the immediate intention. Other options include using both Statement and State APIs (more data storage and transfer, but the advantages of both) and/or to use your applications own data storage in place of the State (faster retrieval, more easily queried).

The most important thing though, is that whatever you do follows what others in the industry are doing with star ratings. The bookmarklet includes star ratings and these are explained in the recipe here. If you're not familiar with recipes, see this page here. If you do store the star ratings in statements to be used in other systems, those statements should follow the bookmarking recipe.

I hope that's helpful!