4.8.1 API Documentation

[Kilrsat]

The 4.8.1 preliminary API is available here:

http://code.snapstream.com/api/btv481

It should be relatively finalized, but we may still add a few more functions.

Fonceur has updated the BTVLibrary developer handy tool already and it is available here:

My updated addons...

[Kilrsat]

The biggest changes:

BTVLicenseManager.Logon() now returns something!!!

It returns a propertybag containing 2 properties, and looks something like this:

<PVSPropertyBag xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.snapstream.com/WebService">
  <Properties xmlns="http://www.snapstream.com/types">
    <PVSProperty>
      <Name>AuthTicket</Name>
      <Value>0f2a5911-a18c-4909-98d5-e71bde3bacdc</Value>
    </PVSProperty>
    <PVSProperty>
      <Name>UserID</Name>

      <Value>8771f287-840f-4a51-979d-2a6e87a591fc</Value>
    </PVSProperty>
  </Properties>
</PVSPropertyBag>

You need to save the AuthTicket property value. This needs to be passed into every other web service call you make. UserID may be useful as well, but there are only a few web services that use it.

Logon() also now has a username property. To make things work just like before, pass "administrator" in as the username.

There is now an explicit, RenewLogonSession() function. If you do not call this within 15 minutes of calling Logon() your AuthTicket will expire and become invalid. Calling this function extends the expiration time on your AuthTicket to 15 minutes from the current time.


The first parameter of basically every web service will be that AuthTicket. If you call functions with an invalid ticket, they will exception and yell at you.

[Kilrsat]

Starting in 4.8, the Beyond TV Web Server supports SSL. This means, you want to access the Web Services in a secure manner (i.e. without using plaintext passwords), you now have the option.

Insecure:
http://<BTVServer>:8129/wsdl/BTVLicenseManager.asmx

Secure:
https://<BTVServer>:8129/wsdl/BTVLicenseManager.asmx

Note:
The Beyond TV server will most likely not have a valid SSL certificate. By default, .Net will exception if you attempting to contact an https:// site that doesn't have a valid cert. To get around this, use this block of code before accessing the web services.

			
using System.Net;
using System.Net.Security;
using System.Security;
using System.Security.Cryptography.X509Certificates;

	ServicePointManager.ServerCertificateValidationCallback += delegate( object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors ) {
			return true;
	};

[Deuce911]

Does this mean that all of the old applications will not work anymore with 4.8 since the login has changed?


Thanks
Mike

[Kilrsat]

Originally Posted by Deuce911

Does this mean that all of the old applications will not work anymore with 4.8 since the login has changed?


Thanks
Mike

Basically, yes. Any application that uses the API needs to be updated.

It's unfortunate, but something that had to be done.

[Kilrsat]

This was the first breaking change in over 3 years (it has remained basically backwards compatible all the way to 3.5), and if it could be avoided, it would have been. Unfortunately, we hit a point where the problems with the old API were too big to ignore.

What this gives you:
1. Easier development. No more having to login to the license manager before you can add a reference to anything else. Just add away.

2. No more random 403 errors. The old method really sucked because if you had your app running and Link running, closing Link resulted in 403 errors for your app. Two different apps running on the same machine would also produce the same problem. In general, multiple applications from single machine were extremely poorly handled before.

3. Security. If you don't want your kids or anyone else to be able to screw with your recordings, you can. Only tell them how to login to a limited account and keep the administrator password in your head. They won't be able to record Desperate Housewives instead of American Gladiators again.

4. Actually knowing who is logged in from where. Check out the new Link Client Management page in the Web Admin.



We did spend a decent amount of time trying to come up with a way to get everything we needed and still offer complete backwards compatibility. But even the best hacked up solution would have simply delayed the point where things stopped working. Since nothing was an actual permanent solution, we decided to draw the line here.

Any existing application should be able to be updated in under 30 minutes. If anyone needs help with it, I'll personally assist them in getting things working.

I'd also like feedback from anyone on what we can do to make development easier in general. I know the web services can be a bit unwieldly at times, but we don't see much of it because we have all kinds of little helper classes in place to make Link happen.

[ZetaVu]

Any chance SS can contact plugin writers directly to alert them to the new changes, or to get source code for the plugins if the original writers are not continuing to support them? Fonceur took care of his which is awesome, right now I'm trying to get btv smartie updated. This would help if these changes could be made in the prebeta.

[79DieselRabbit]

Originally Posted by Kilrsat

There is now an explicit, RenewLogonSession() function. If you do not call this within 15 minutes of calling Logon() your AuthTicket will expire and become invalid. Calling this function extends the expiration time on your AuthTicket to 15 minutes from the current time.

Is RenewLogonSession() the only way to renew a login, or can Logon() be used again to renew it? If so, is there a down side to doing this?

[Kilrsat]

Only RenewLogonSession will renew. Calling Logon again will create a new session with a new AuthTicket.

[romanoj]

I just found out about this API change. I too am disappointed about it. If it's a necessary evil, I understand but it will be a headache to many third party developers.

I'm on the prebeta test group so I was able to download a copy of 4.8.1 to try it out. Sure enough, the Javascript code written for our MediaMVP BTV project doesn't work with the new API. The MediaMVP code has to be updated. It's not easy since there is alot of service calls. It will basically make the MediaMVP BTV users dead on arrival with v 4.8.1. It won't make people happy. I will see if I can figure out this new API returned AuthTicket but try to fix it before it is released but if I don't there were be some unhappy customers.
(p.s. besides being a past developer of MediaMVP BTV project, I use the MediaMVP. So I have an incentive to fix it for myself. If not, I may not upgrade to 4.8.1)

[bpsmicro]

I'm a "light" user of my MVP, so for now I'm not going to downgrade my 4.8.1 install. So if you need a beta tester for any of the MVP updates, PM me. I *only* use the MVP for watching recorded shows, so you definitely don't want me at the only beta tester. :-)

SnapStream, you'd be very wise to ensure that, when you release 4.8, your announcement is very, very clear on the fact that *all* add-ins will be broken and require updates. In fact, you'd be wise to provide direct links to the updated versions for all the known popular ones. If you do nothing, and let everybody not on the beta find out for themselves the hard way, guess who they're going to be pissed off with (Hint: *not* the add-in authors).

Brad.

[Mike DiBella]

I do not understand why Snapstream wouldn't offer a "compatibility proxy" as a separate web application process for legacy compatibility.

The new API should be hosted a a new URI, with the old API continuing to be available at the legacy URI ONLY if the proxy is running. The proxy simply maps the old interfaces to new API calls.

Only users who must have both NEW features and compatibility with OLD plug-ins would need to suffer the costs associated with running the proxy.

Is the color of the sky in my world not blue?

[merrypig]

Not much point locking the front door if you're going to leave the back door wide open.

[Mike DiBella]

We did spend a decent amount of time trying to come up with a way to get everything we needed and still offer complete backwards compatibility.

Where do you read "locking" anything as a stated design goal?

[Fonceur]

If I run my addon on the BTV server, the LicenseManager.GetVersionNumber() (or the login) takes a fraction of a second to return a result. When I do the same from another machine on the network, it takes 15 seconds...

How would I check if the extra delay comes from the Windows networking/firewall or if it's from the BTV web server? I tried debugview, but it only mentions when the session is starting...