StreamSpin

The StreamSpin query API

The StreamSpin query API provides an alternative to using the StreamSpin web-service API.

The query API allows developers to interact with StreamSpin using ordinary http request.

The signatures and timestamps must be created in the same manner as with the web-service methods.

The query parameters must be named using the actual parameter names, e.g., The GetSId method takes a parameter called addToServiceTitle.

The http call is:

http://query.streamspin.com?action=GetSId&addToServiceTitle=test&....

The action parameter should not be included in the signature.

Pleace note that the parameter values in the HTTP request must be URL encoded.
This should be done AFTER the signature has been calculated.
If you are using .Net this can be done with the HttpUtility.UrlEncode() method.
If not use the corresponding methods in your programming language or use the table with escape characters from Wikipedia

Web service URLs

http://servicesubscriptions.streamspin.com/service.asmx http://serverservices.streamspin.com/UserLocation.asmx http://serverservices.streamspin.com/contentpublishing.asmx

The servicesubscriptions Web service

The following methods are available via the servicesubscriptions web-service:

ChangePublicStatusOfService
CreateApprovedMultiSubscription
CreateApprovedSubscription
CreateMultiSubscription
CreatePrivateService
DeleteService
CreateSubscription
GetSId

ChangePublicStatusOfService

The ChangePublicStatusOfService allows an external website to change the status of a private service between public, i.e., all users can subscribe to the service, and non-public, i.e., only the creator can subscribe.

public bool ChangePublicStatusOfService(
          int editorId,
          bool newPublicStatus,
          int serviceId,
          string signature,
          string timestamp)

The method takes a serviceId, and a the new status of the service, i.e., true or false. The method returns a boolean value indicating whether or not the update succeeded.

CreateApprovedMultiSubscription

The CreateApprovedMultiSubscription method allows trusted service providers to create approved subscriptions for a list of users. This means that the users will begin receiving content from the service provider instantly, without manually having to approve the subscription. If you feel that you should be a trusted service provider, please contact us at rw [@] cs.aau.dk or khp1412 [@] cs.aau.dk.

public void CreateApprovedMultiSubscription(
          int serviceProviderId,
          string serviceProviderPassword,
          int[] subscribedUserIds,
          int[] serviceIds)

The method parameters are the service provider id and password, along with an integer array of userids, and an integer array of serviceids.
Each userid must have a matching serviceid, i.e., the length of the arrays must be similar. The matching arrays of service and userids, allows for individualized service subscriptions. If the same service id is to be used for all subscriptions, then this id must be present for each user id.

CreateApprovedSubscription

The CreateApprovedSubscription method creates an approved subscription for a single user, i.e., the user will begin recieving service content immediatly without having to manually approve the subscription.

public void CreateApprovedSubscription(
          int serviceProviderId,
          string serviceProviderPassword,
          int subscribedUserId,
          int serviceId,
          bool isPublic)

The method takes a service provider id and password. The id of the user begin subscribed, along with a serviceid to which to subscribe.
The isPublic parameter indicates whether the service is private or public.

CreateMultiSubscription

The CreateMultiSubscription method creates a subscription for a list of users in the same way as the CreateApprovedMultiSubscription method.
Only diffence being that each user has to manually approve the subscription before receiving content. The CreateMultiSubscription method is available to everyone, unlike the CreateApprovedMultiSubscription method that are only available to trusted service providers.

public void CreateMultiSubscription(
          int serviceProviderId,
          string serviceProviderPassword,
          int[] subscribedUserIds,
          int[] serviceIds)

CreatePrivateService

Creates a private service.

The service groups and ids can be seen in the Service Group item below.

public int CreatePrivateService(
          bool allowMultiSubscription,
          string description,
          int groupid,
          bool isPublic,
          string name,
          bool requiresSetup,
          string signature,
          string startServiceUrl,
          string subscriptionPassword,
          string timestamp,
          string url,
          int userid
          string[] tags
          string serviceScriptUrl
          string serviceScript
)

The tags should not be used in the signature.

DeleteService

Deletes a service.

public int DeleteService(
          int serviceId,
          string signature,
          string timestamp
)

CreateSubscription

Creates a non-approved subscription in the same way as the CreateApprovedSubscription method.

public void CreateSubscription(
          int serviceId,
          int serviceProviderId,
          string signature,
          int subscribedUserId,
          string timestamp)

GetSId

The GetSId method creates a copy of the service to which a user is trying to subscribe. i.e., if a user is trying to subscribe to a service which send user specific content, then the user needs to subscribe to a unique serviceid.

One example of a subscription where the user needs to subscribe to a unique service is the email service. If all users subscribed to the same service(id), then all users would recieve everyones emails.

Therefore a new service (a copy) is created using the GetSId method, and the user subscription is created using the id of the service copy.

If however the service broadcast info on your favorite football team, then everyone would subscribe to the same service id. In this scenario no service copy would be made, and the user would be subscribed without a call to the GetSId method.

public int GetSId(
          string addToServiceTitle,
          int editorUserId,
          bool makePublic,
          bool publicService,
          int serviceId,
          int serviceProviderId,
          string signature,
          string timestamp,
          string url,
           bool useParent)

How do I use the webservices to subscribe a user to a private service?

The following is a piece of code which will create a subscription copy of an existing private service.
The code uses a dll, which is freely available in the top of this page, to create a timestamp, and to create a signature.

The signature is created using a secret key available from the MyAccount tab on the streamspin webpage.

The text used in the signature is the various GetSId parameters in alphabetic order.

The GetSId method is then called to create a private service subscription copy. This allows the service server to send messages to individual users.

The GetSId method returns a new service id or a web-service error code.

string timestamp = CryptoLib.Signatures.CreateTimeStamp(DateTime.Now);

string text =
     txtSubscriptionName.Text + //addToServiceTitle
     Session["sUserId"].ToString() + //subscribed user id
     "False" + //it is not a public service
     "False" + //do we make the service public
     Session["sOriginalServiceId"].ToString() + //original service id
     "8" + //service provider id
     timestamp +
     "http://www.streamspin.com/flickr.aspx" + //setup url
     "True"; //use parent

string signature = CryptoLib.Signatures.Sign(text, "[KEY]");

int newServiceId = subscriptionService.GetSId(
     txtSubscriptionName.Text,
     false,
     Convert.ToInt32(Session["sUserId"]),
     false,
     Convert.ToInt32(Session["sOriginalServiceId"]),
     8,
     signature,
     timestamp,
     "http://www.streamspin.com/flickr.aspx",
     true);

The userlocation Web service

The user location web-service can be used to register user location request with the StreamSpin server.

A request is registered using the RegisterUserLocationRequest method, and the registering service will now recieve a new location whenever the user moves further than a given threshold.

The following methods are available via the userlocation web-service:

RegisterUserLocationRequest
UnRegisterUserLocationRequest

RegisterUserLocationRequest

The RegisterUserLocationRequest method tells the StreamSpin server that your web-service or web-page want to recieve notifications whenever a user moves further than a given threshold.

public bool RegisterUserLocationRequest(
          int movementThreshold,
          int serviceId,
          string timestamp,
          int userId,
          string webServiceUrl,
          string signature
)

The changed user location is sent using HTTP, and if you are using a web-service, then the web-service must contain the following method.

public bool RecieveUserLocation(
          int userId,
          double lat,
          double lng){...}

The following changes to the web-config file is needed in order to make a web-service recieve http-parameters.

<system.web>
     <webServices>
           <protocols>
               <add name="HttpGet" />
               <add name="HttpPost" />
          </protocols>

If a web-page is used, then the web-page can make use of the following 3 request parameters:

          int userId = Convert.ToInt32(Request.QueryString["userId"]);
          double lat = Convert.ToDouble(Request.QueryString["lat"]);
          double lng = Convert.ToDouble(Request.QueryString["lng"]);

Example

The following example demonstrates a web-service used for recieving user locations registered using the RegisterUserLocationRequest web-service method.

The sample RecieveUserLocation method communicates with a service server using a socket.

using System;
using System.Web;
using System.Collections;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Net;
using System.Net.Sockets;
using System.IO;
using System.Runtime.Serialization.Formatters.Binary;

[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Service : System.Web.Services.WebService
{
     string server = [SERVER ADDRESS];
     private int port = [SERVER PORT];

     public Service ()
     {

     }

      [WebMethod]
      public bool RecieveUserLocation(int userId, double lat, double lng)
     {
          TcpClient tcpClient = null;

           try
           {

//create a binary writer

                BinaryFormatter binFormatter = new BinaryFormatter();
                MemoryStream ms = new MemoryStream();

                tcpClient = new TcpClient(server, port);
                Stream stream = tcpClient.GetStream();
                BinaryWriter binWriter = new BinaryWriter(stream);

//the id of the user on which location changes is requested.

binWriter.Write(userId);

//the webservice url to which changes must be sent

binWriter.Write(lat);

//the thresshold to when changes must be sent

                binWriter.Write(lng);
          }
          catch (Exception ex)
          {
                return false;
          }
          finally
          {
                tcpClient.Close();
          }
          return true;
          }
}

UnRegisterUserLocationRequest

The UnRegisterUserLocationRequestWeb unregisters request made using the RegisterUserLocationRequest web-service method.

public bool UnRegisterUserLocationRequest(
          int serviceId,
          string signature,
          string timestamp,
          int userId,
          string webServiceUrl
)

The contentpublishing Web service

The following methods are available via the contentpublishing web-service:

PublishPublicContent
PublishPrivateContent

PublishPublicContent

Signature = content.Description + content.Url + serviceid.ToString() + timeStamp;

The PublishPublicContent method can only be used by trusted service providers. Please contact the StreamSpin team if you think you should be a trusted provider.

PublishPrivateContent

Signature = content.Description + content.Url + serviceid.ToString() + timeStamp;

The PublishPrivateContent method uses a ContentPublisher and Content object to publish public content to service users.

public bool PublishPrivateContent(
          Content content,
          int serviceid,
          int serviceid,
          int serviceProviderId,
          string signature,
          string timeStamp)

The following example is the actual content publishing functionality of the TourBuilder service server.

//create a contentpublishing object

contentpublisher.ContentPublishing cp = new contentpublisher.ContentPublishing();

//create a content object

contentpublisher.Content content = new contentpublisher.Content();

//set the content description to the tour name, followed by the sight name

content.Description = string.Format("Tour : {0}", seightNames[seightPair.Key]);

//content url http + tour id + seight id.

content.Url = string.Format("http://tourbuilder.streamspin.com/ShowSeight.aspx?seightid={0}", seightPair.Key);

Console.WriteLine("Sending seight" + seightPair.Key.ToString());

string timestamp = CryptoLib.Signatures.CreateTimeStamp(DateTime.Now);

string text = content.Description + content.Url + serviceId.ToString() + [YOUR SERVICE PROVIDER ID] + timestamp;

string signature = CryptoLib.Signatures.Sign(text, [YOUR KEY]);

int returnVal = cp.PublishPrivateContent(content, serviceId, [YOUR SERVICE PROVIDER ID], signature, timestamp);

Service Groups and Ids

Id	Name
4	Computers
7	Education
3	Movies
2	Music
5	Science
1	Sports
6	Transport

Creating an UTF timestamp

The timestamp can either be created using the CryptoLib C# class library, or by creating your own timestamp from the current universal time (UTC) as YYYY-MM-DDTHH:MM:SSZ.

string timestamp = "YYYY-MM-DDTHH:MM:SSZ";

Creating a signature

The signature is created by making a text string from the input parameters. The order of the parameters must be alphabetic.
The GetSId() web-service method requires a signature created from:

     string signatureText = addToServiceTitle +
                              publicService.ToString() +
                              editorUserId.ToString() +
                              makePublic.ToString() +
                              serviceId.ToString() +
                              serviceProviderId.ToString() +
                              timestamp +
                              url +
                              useParent.ToString();

All parameters must be strings.

You must then use the signing key that are available from the My Info web-page and create the signature using the CryptoLib class library.

string signature = CryptoLib.Signatures.Sign(signatureText, "YOUR KEY");

The signature can now be used in the call to the GetSId() method.

The signature is created similarly for the other webservice methods with the parameters alphabetically sorted.

The following method can be used as a blueprint for creating your own signature method.

     public static string Sign(string text, string key)
     {
          HMAC sHash = HMACSHA1.Create();

          byte[] textBytes = Encoding.UTF8.GetBytes(text);
          byte[] keyBytes = Encoding.UTF8.GetBytes(key);

          sHash.Key = keyBytes;

          return Convert.ToBase64String(sHash.ComputeHash(textBytes));
     }

Web service Error Codes

The following is a list of StreamSpin Error codes.

     -994          Wrong usertype
     -995          Wrong password
     -996          Expired timestamp
     -997          SQL Server Error
     -998          Signature can not be validated
     -999          Unknown Error