NewsGator API ClipItems Method

If you're using the newest version of the NewsGator Toolbar, hopefully you've noticed the new "Clip" feature that I built into it.  It's a pretty cool feature that allows you to clip any webpage to your NewsGator clippings.  You can then use your clippings to build your own link blog and link feed.

Since this method is pretty new, it's not in our online documentation yet, so I thought I would write about it and show some C# example code of how to use it.

I should note that this method is currently restricted by your API token so you don't have access to it... but if you want access, you can contact our Brian Kellner (NewsGator Director of Product Managment) for more details.

ClipItems lives on the PostItem.asmx endpoint.  It's a pretty simple call to make on the client side since all the cool magic happens on the server.

The request signiture looks like this:

POST /ngws/svc/PostItem.asmx HTTP/1.1
Host: services.newsgator.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
xmlns:xsd=http://www.w3.org/2001/XMLSchema 
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Header>
    <NGImpersonate xmlns="http://services.newsgator.com/ngws/Impersonate">
      <ImpersonateUser>string</ImpersonateUser>
    </NGImpersonate>
    <NGAPIToken xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
      <Token>string</Token>
    </NGAPIToken>
  </soap12:Header>
  <soap12:Body>
    <ClipItems xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
      <clipList>
        <ClippedItem>
          <PostId>string</PostId>
          <Url>string</Url>
          <Title>string</Title>
          <FolderId>int</FolderId>
        </ClippedItem>
        <ClippedItem>
          <PostId>string</PostId>
          <Url>string</Url>
          <Title>string</Title>
          <FolderId>int</FolderId>
        </ClippedItem>
      </clipList>
    </ClipItems>
  </soap12:Body>
</soap12:Envelope>

In my use case, I don't pass in a PostId since I don't have one. I let the service figure that part out for me. Instead I only pass in the URL, Title and FolderId.  If you have a PostId, you should pass that as well to make the work on the backend less intensive.

The service return signiture looks like this:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
xmlns:xsd=http://www.w3.org/2001/XMLSchema 
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <ClipItemsResponse xmlns="http://services.newsgator.com/ngws/svc/PostItem.asmx">
      <ClipItemsResult>
        <ClippedItem>
          <PostId>string</PostId>
          <Url>string</Url>
          <Title>string</Title>
          <FolderId>int</FolderId>
        </ClippedItem>
        <ClippedItem>
          <PostId>string</PostId>
          <Url>string</Url>
          <Title>string</Title>
          <FolderId>int</FolderId>
        </ClippedItem>
      </ClipItemsResult>
    </ClipItemsResponse>
  </soap12:Body>
</soap12:Envelope>

You basically get the exact same structure back, but with all the values filled in.

So let's look at a C# example of how to clip the NewsGator homepage to your "My Clippings" folder.  You'll need the URL (http://www.newsgator.com), the Title (NewsGator - The RSS Company) and the FolderId (your "My Clippings" folder is always FolderId 0).  Lets also assume that you've already added a Web Reference to PostItem.asmx and called it PostService.

public void ClipNewsGatorHomepage()
{
    // first, let's setup some variables
    string url = "http://www.newsgator.com";
    string title = "NewsGator - The RSS Company";
    int folderId = 0;

    // now lets create the PostItem proxy object
    PostService.PostItem postWebService = new PostService.PostItem();

    // next, create a new ClippedItem object and set it's properties
    PostService.ClippedItem clipItem = new PostService.ClippedItem();
    clipItem.FolderId = folderId;
    clipItem.Title = title;
    clipItem.Url = url;

    // finally, make the call and get the results
    PostService.ClippedItem[] clipItemResults =
postWebService.ClipItems(new PostService.ClippedItem[] { clipItem });

    // do whatever with the results
}

That's it! Now you've clipped the NewsGator Homepage to your "My Clippings" folder!