One of the nice things about HP MediaBin is that pretty much everything you can do as a user, you can also do programmatically using the MediaBin Web service layer. This often-overlooked aspect of MediaBin allows you to enhance your MediaBin solution with custom code written directly to the MediaBin API.

Customers have done some amazing things over the years with the APIs; from simple scripts used to accomplish a specialized task, to creating custom user interfaces (UI) for specific use cases. The good news is MediaBin 8 includes everything you’ll need to get started.

In this multi-part posting, we will walk through everything you’ll need to harness the MediaBin API. Today, we will walk through a basic example. In subsequent posts, we will explore the MediaBin API in depth, so stay tuned.

Connecting:

The primary interface to MediaBin 8 is Web service based. By default it is usually installed on the machine hosting your JBoss front-end. It will respond to a request on http://<machinename>/MBWS/MediaBinWebService/VirageMediaBinServer.asmx with a list of all available services, which will look something like this:

MediaBin’s Web service API is SOAP-based, so if you’re planning on doing any coding against it, you’ll want to use tools supported by your language of choice to encapsulate its interface into nice, friendly native-language artifacts. For Java, I usually use the JAX-WS implementation in Apache’s Axis 2.0. The older Axis 1.0 bindings are also a solid choice. For Python, I’ve had good success with SUDS. Your language of choice will have a similar tool. Using these makes coding against a Web service API just as simple as using any other library. The WSDL for MediaBin’s Web services is available from:

You’ll need to provide the WSDL to your tool of choice to generate the appropriate bindings.

Logging in:

While you might expect the process of getting logged into MediaBin through the Web service layer to be the simplest step, it actually involves a little bit of finesse. After MediaBin successfully validates your credentials, it will return an authentication token as a cookie in its reply to the logon request. Once logged into MediaBin, each subsequent request must send this cookie in the HTTP header to allow the Web services layer to establish the identity of the requestor. You’ll need to tell your binding to do this for you. Otherwise, you’ll get a successful reply from the logon, but all your subsequent requests will fail with an error indicating that you’re “not logged in”.

Under Python using SUDS, you’re already covered; the default binding already preserves any cookies returned into the cookie jar.

From here, you can simply log in using whatever credentials you would have given to the MediaBin client UI:

MBConnectedUser loReply = vmb.mbSessionLogon("username",
"password");

Note that all permissions associated with the user under which you log into MediaBin via Web services are exactly the same as the permissions that user would have logging into the Web client.

Now that we’re logged in, we have the full API at our disposal. We will explore the API in depth as the subject of a later blog. For today, we‘ll just perform one simple operation – returning a list of collections.

The first thing to note is that the Web service API uses “Pagers” to return “arbitrary-length” responses. These are very helpful constructs, but also require a little bit of an introduction.

Pagers:

The Pager construct allows you to work through an arbitrarily large chunk of data a little bit at a time. For example, if you need to process the contents of a MediaBin Collection or Folder in some way, a pager lets you handle bite-sized chunks rather than attempting to handle the entire contents (which could number in the thousands) at once. While there’s a little more work involved to set one up, the benefit in using them is that your code will be prepared to handle as many items as it might encounter.

Creating a pager is pretty simple – you’ll note there are specific pager types for all of the “container-type” objects in MediaBin; folders, collections, etc. The API calls we’ll be using here are all in the group of “mbPagerCacheCreate…” calls. For example, these Java snippets will create a pager to enumerate all of the collections (visible to the user you logged in as):

String myPager = vmb.mbPagerCacheCreateCollectionPager("");

Once you have a pager, iterating through it is done in the following way:

Note that the last page will usually have fewer items than you requested.

One twist to keep in mind is that a pager is not a snapshot. Each time you request a page, the API returns the page based on the state of the server at the time the page is requested, not as it was when you initially created the pager. If the state of the object you are examining has changed since you created the pager, those changes will be reflected in the pages you retrieve. Sometimes this can lead to confusing results.

Logging out:

Since MB is licensed by concurrent user count, be sure to log out as soon as your code is finished. Users connecting through the Web service API are the same as any other connected user as far as the licensing model (and pretty much everything else) is concerned. To log out:

vmb.mbSessionLogoff();

And that’s it! In Part 2, we will go into the API in more depth and discuss the major concepts to provide you with the details needed to build your own custom applications.