Hello,Yes, it is available for use now. We have some basic notes up on our Dev Wiki (http://developer.newsgator.com/wiki/index.php?title=Posts#Post_Service_Overview) on how to use it. I have not updated the REST UpdatePostMetadata section yet, but you can also refer to the SOAP section to get more information. I only mention that because next week I will get around to updating the REST UPM section.
Couple of notes for use:
1.) Important that you use the correct location name in the xml document you are sending in. This is critical for synchronization to know what location is submitting the changes.
2.) Use of the synchronization token. Along with the location name, the sync token is critical to managing the information that has changed since the last time you made the call. This synchronization token can be used interchangeably with subscription.aspx/getupdates and subscription.aspx/getsubscriptionlist. The "ETag" header will contain an updated/new sync token. Obtaining a sync token from getupdates is the best place to start.
3.) You can specify one-to-many feedmetdata nodes, one for each feed. For each feedmetadata node, specify one-to-many postmetadata nodes, one for each post. If you are submitting a new read state (i.e., ng:state), make sure you specify "True" for ng:statespecified. Likewise with ng:flagState, specify "True" for ng:flagStateSpecified so that the system knows you are submitting a new flag state.
4.) If you want to check and see if any "new" states or flags have been changed for your machine's location, you can submit a xml doc that only contains the definitions for location, sync token, and updaterelevancescores (set it to false). The results should contain any changes from other devices, if there are any.
The following example are results from calling my location with a skeleton xml doc to see if any changes were present. You can see 3 posts in 2 different feeds were returned; 2 marked read (1) and 1 marked deleted (2). There was also a flag state change too for the last post.
<ng:states xmlns:ng="http://newsgator.com/schema/extensions">
<ng:feed ng:feeId="50902">
<ng:post ng:postId="2211400183" ng:state="1" ng:stateSpecified="True" ng:flagState="0" ng:flagStateSpecified="True" />
<ng:post ng:postId="2211400184" ng:state="1" ng:stateSpecified="True" ng:flagState="0" ng:flagStateSpecified="True" />
</ng:feed>
<ng:feed ng:feedId="50903">
<ng:post ng:postId="2211400196" ng:state="2" ng:stateSpecified="True" ng:flagState="9" ng:flagStateSpecified="True" />
</ng:feed>
</ng:states>
As for synchronization, here is a couple of thoughts too:
1.) subscription.aspx/<locid>/getupdates?tok=<sync token> is the controller. This endpoint provides the necessary information on when to call subscription.aspx/<locid>?tok=<sync token> (changes to subscription list) or feed.aspx/<feedId>?tok=<sync token> (feed content updates).
2.) If getupdates xml results returns feedIds, you should call feed.aspx/<feedId>?tok=<sync token> for each feedId to obtain the necessary content updates. Note that the sync token used for this endpoint should NOT be used interchangeably with other endpoints. Each feed should have its own sync token for this call. A new/udpated sync token is returned in the channel node in the ng:token element.
3.) If getupdates attribute subscriptionsChanged is set to "True", this indicates something has changed with the given subscription list, could be a new subscription, new folder, subscription name change, etc... Although this endpoint does take a sync token, the token does not return only the changes since the last call. The sync token actually flips the values for unseen, unread, and update values. You can reference these values as necessary, but the functionality has been moved up to the "controller" getupdates endpoint - just ignore them for now. However, we have a feature request to change it so that the output only returns the changes to keep the result set and bandwidth to a minimum. A new/updated sync token is returned in the opml root node in the ng:token attribute.
4.) We have not integrated an indicator into getupdates to notify when to call updatepostmetadata (upm) if there are changes available. That is also logged as a feature request. So for now, just know that you will want to call upm periodically to either submit post state/flag changes or to retrieve them. Remember, the new/updated sync token is returned in the "ETag" header!
Hope this helps,
Thanks,
Rob