Vidispine SDK for Visual Studio .NET

By Vidispine - May 17, 2015 (Last updated: April 3, 2017)

The easiest way to get to know the API via .NET!

One advantage of a REST API is the decoupling between the two parties: in theory all that requires is a verb, a self-explanatory URI and some request/response bodies. Having an SDK can make development easier, though. Below is a DLL that is automatically generated from the WADL and XSDs of the Vidispine service.

The DLL contains:

  • Methods to access all resources in the Vidispine API (/API). These are generated using the WADL.
  • Classes of all Vidispine XML entities. These are generated using the XJC tool from Visual Studio.
  • Code to convert from instances of anonymous classes to XML classes.

There is one particular part that is not yet generated with the automatic creation of the classes: documentation. However, using IntelliSense in Visual Studio it is quite easy to use the different methods.

Getting Started

We assume that you have a Vidispine system installed, either locally or via our cloud service.

Now create a .NET project in Visual Studio. For this example, we are using C# in VS2013 (any version). Add the DLL file as dependency. The SDK is in the Vidispine.VidiNET namespace.

First we need to get the root resource. Easy. We might just as well authenticate at the same time.

var rootResource =
    new VidispineResource("http://localhost:8080/API/")
    .Authenticate("admin", "admin");

Let’s get an item from our system.

var searchResource =
    rootResource
    .Item
    .Search;
var itemList = searchResource
    .Number(1)
    .CallXml(new ItemSearchType());

What does this mean? Keep the apidoc page open. You will notice that every path segment in the REST API will correspond to a property (“Item”) in the .NET chain. The code snippet also shows that you can, at any point, store the current chain and reuse it later. At the end of the chain there is a verb, which corresponds to what you want to do with the REST resource (“Search”). After the verb, any query or matrix parameters are set. (Good news: you don’t have to worry about if it is a query or matrix parameter.)

Finally, there is the just-do-it command (“CallXml”). CallXml means call the method and expect XML result back (as per the apidoc page). The argument to CallXml is the input. In this case, a generated type from the XML Schema.

As I said, CallXml() returns an XML object back. We show it.

Console.WriteLine(itemList.item[0].id);

Actually, we can get the metadata for the item.

var metadata =
    rootResource
    .Item
    .Id(itemList.item[0].id)
    .Metadata
    .GetMetadata
    .CallXml();

A bit talkative? Yes, I admit that. Good thing there is IntelliSense. We could have used the combined call, to reduce the number of calls:

var metadata = searchResource
    .Number(1)
    .Content("metadata")
    .CallXml(new ItemSearchType())
    .item[0]
    .metadata;

Also, note that you can use extension methods to extend the API yourself.

XML objects

Let’s search for something. Now you’ll find the .NET’s methods for creating XML objects can be a bit clumpsy. (To say the least.)

ItemSearchType itemSearchType = new ItemSearchType();
ItemSearchTextValueType itemSearchValueType = new ItemSearchTextValueType();
itemSearchType.text = new ItemSearchTextValueType[] { itemSearchValueType };
itemSearchValueType.Value = "dvvideo";
var result = searchResource.CallXml(itemSearchType);

Not really usable. So we added a function to create XML objects using anonymous objects. The equivalent to the five lines above:

var result = searchResource.CallXmlObj(new { Text = "dvvideo" });

You’ll find that the anonymous object notation resembles JSON notation. Very short. Unfortunately not type-safe at all.

What else

If the server can’t be reached, you will get a System.Net.WebException. If Vidispine returns an error, you will get one of (Vidispine.VidiNET namespace):

  • FileAlreadyExistException
  • ForbiddenException
  • NotYetImplementedException (sorry)
  • NotFoundException
  • LicenseFaultException
  • NotAuthorizedException (this is if you have the wrong rights to a resource, not if you enter wrong password)
  • InvalidInputException
  • InternalServerException

Now what?

The SDK DLLs are available here in our Support Portal (login needed).

There you can find the SDK for all our current versions of Vidispine. The SDK  is (of course) compatible with older/newer versions as well, as long as the underlying REST call is present.

And then?

The SDK is still under development. Hence we very much would like your input. The aim is to add more documentation into the WADL file, which then will be automatically transferred to the SDK. Also, documentation around the anonymous objects will be written.

Categories

TechnologyVidispine