Therefore Web API Programming Interface 1.0

Non US-ASCII characters in user-names or passwords

 

User-names or passwords containing characters outside the US-ASCII character repertoire will cause interoperability issues between the Web API server and clients, unless both communication partners agree on what character encoding scheme is to be used. Client can inform the Web API server about the character encoding via the Therefore-Auth-Codepage HTTP header passing the code page number of the encoding:

 

Therefore-Auth-Codepage: <code page number>

 

If the Therefore-Auth-Codepage header is not set in the HTTP request, a default code page/encoding will be used on the Web API server for the received user-name and password. The default code page depends on the system language.

 

Here is an example how the Therefore-Auth-Codepage HTTP header looks like in a request:

 

 

 

List of code pages accepted by Therefore Web API:

 

 

Examples (C#/WCF)

 

To set the Therefore-Auth-Codepage HTTP header in a .Net WCF client you can use the endpoint behavior from the Web API SDK Samples. The behavior class name is CredentialsCodePageProviderBehavior. You also can find the behavior in Therefore.WebAPI.Service.Contract.dll in Therefore.WebAPI.Service.Contract.Extensions namespace.

 

To see how to use this behavior, refer to the Web API SDK samples:

osee the SharedServiceReference.ClientConnection.CreateClientBasicAuth() method if you use service reference;

oor the Common.ThereforeServiceConnection.CreateChannelFactory() method if you use shared contract DLL.

 

 

Connection and Authentication Samples

 

In this section you can find code samples about how to connect to the Web API. Please see Web API SDK Samples for more details.

 

 

 

 

Connection and Authentication by using web references (auto generated proxy)

For full code sample, please see OldClient_Net20.csproj project in WebAPI SDK Samples.

See also: Add Service Reference in Visual Studio

 

Basic authentication:

 

 // 1. Declare Web API Service Client.

 OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword service;

 

 // 2. Set tenant name if required.

 if (!String.IsNullOrEmpty(tenantName))

         service = new ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport(tenantName);

 else

         service = new OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword();

 

 // 3. Set credentials

 // TODO: Set correct user name/password of Thereforeâ„¢ user

 NetworkCredential netCredential = new NetworkCredential("username", "userpassword");

 Uri uri = new Uri(service.Url);

 ICredentials credentials = netCredential.GetCredential(uri, "Basic");

 service.Credentials = credentials;

 service.PreAuthenticate = true;

 

 // 4. Execute web operation

 GetCategoriesTreeResponse response = service.GetCategoriesTree(new GetCategoriesTreeParams());

 

 // 5. Process response

 MessageBox.Show("Found :" + response.TreeItems.Length.ToString());

 

 

 Extend automatically generated proxy to support tenants

 

 public class ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport : OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapUserPassword

 {

         private string tenantName;

 

         public ThereforeWS0001_SoapUserPasswordHttpsWithTenantSupport(string tenantName)

         {

                 this.tenantName = tenantName;

         }

 

         protected override System.Net.WebRequest GetWebRequest(Uri uri)

         {

                 var request = base.GetWebRequest(uri);

                 request.Headers.Add("TenantName", tenantName);

                 return request;

         }

 }

 

 

Windows integrated authentication:

 

 // 1. Declare Web API Service Client.

 OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials service;

 

 // 2. Set tenant name if required.

 if (!String.IsNullOrEmpty(tenantName))

         service = new ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport(tenantName);

 else

         service = new OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials();

 

 // 3. Set credentials

 service.UseDefaultCredentials = true;

 

 // 4. Execute web operation

 GetCategoriesTreeResponse response = service.GetCategoriesTree(new GetCategoriesTreeParams());

 

 // 5. Process response

 MessageBox.Show("Found :" + response.TreeItems.Length.ToString());

 

 

 Extend automatically generated proxy to support tenants

 

 public class ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport : OldClient_Net20.ServiceRef_Update_it_.ThereforeWS0001_SoapWinCredentials

 {

         private string tenantName;

 

         public ThereforeWS0001__SoapWinCredentialsHttpsWithTenantSupport(string tenantName)

         {

                 this.tenantName = tenantName;

         }

 

         protected override System.Net.WebRequest GetWebRequest(Uri uri)

         {

                 var request = base.GetWebRequest(uri);

                 request.Headers.Add("TenantName", tenantName);

                 return request;

         }

 }

 

 

Connection and Authentication by using service references (configuration in file)

 

        /// <summary>

        /// Creates service client by using basic credentials.

        /// </summary>

        /// <returns></returns>

        private ThereforeServiceClient CreateClientBasicAuthConfig()

        {

            ThereforeServiceClient client = new ThereforeServiceClient("ThereforeWS0001_SoapUserPassword");

            client.ClientCredentials.UserName.UserName = "username";

            client.ClientCredentials.UserName.Password = "userpassword";

 

            return client;

        }

 

        /// <summary>

        /// Creates service client by using windows current user credentials.

        /// </summary>

        /// <returns></returns>

        private ThereforeServiceClient CreateClientWindowsAuthConfig()

        {

            ThereforeServiceClient client = new ThereforeServiceClient("ThereforeWS0001_SoapWinCredentials");

            return client;

        }

 

Connection and Authentication by using service references (configuration via code)

 

        private ThereforeServiceClient CreateClientBasicAuth()

        {

            //TODO: update it to the actual values

            string EndpointUriSoapun = "http://<servername>:8001/theservice/v0001/soapun";

 

            //basic

            BasicHttpBinding binding = new BasicHttpBinding();

            EndpointAddress address = new EndpointAddress(EndpointUriSoapun);

 

            binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;  //NOTE: use it for http protocol

            //binding.Security.Mode = BasicHttpSecurityMode.Transport;  //NOTE: use it for https protocol

            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;

            binding.MaxReceivedMessageSize = int.MaxValue;

            binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

            binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

            ThereforeServiceClient client = new ThereforeServiceClient(binding, address);

            client.ClientCredentials.UserName.UserName = "username";

            client.ClientCredentials.UserName.Password = "userpassword";

 

            return client;

        }

 

        private ThereforeServiceClient CreateClientWindowsAuth()

        {

            //TODO: update it to the actual values

            string EndpointUriSoapwin = "http://<servername>:8001/theservice/v0001/soapwin";

 

            //win

            BasicHttpBinding binding = new BasicHttpBinding();

            EndpointAddress address = new EndpointAddress(EndpointUriSoapwin);

 

            binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;  //NOTE: use it for http protocol

            //binding.Security.Mode = BasicHttpSecurityMode.Transport;  //NOTE: use it for https protocol

 

            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows;

            binding.MaxReceivedMessageSize = int.MaxValue;

            binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

            binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

            ThereforeServiceClient client = new ThereforeServiceClient(binding, address);

            return client;

        }

 

 

Connection and authentication by using the Web API Contract DLL

For more details see Common.csproj project in WebAPI SDK Samples.

See also: Add Web API Contract Dll

 

Basic authentication:

 

 // 1. Initialize binding.

 BasicHttpBinding binding = new BasicHttpBinding();

 

 // 2. Set binding properties.

 if (useHttps)

         //for https protocol

         binding.Security.Mode = BasicHttpSecurityMode.Transport;

 else

         //for http protocol

         binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;

 

 //use basic credentials

 binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;

 binding.MaxReceivedMessageSize = int.MaxValue;

 binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

 binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

 // 3. Set server endpoint address.

 EndpointAddress endpoint = new EndpointAddress(EndpointUriSoapun);

 

 // 4. Create a channel factory to the web service endpoint

 ChannelFactory<IThereforeService> channelFactory = new ChannelFactory<IThereforeService>(binding, endpoint);

 

 // 5. Set credentials

 // TODO: Set correct user name/password of Thereforeâ„¢ user

 channelFactory.Credentials.UserName.UserName = "username";

 channelFactory.Credentials.UserName.Password = "userpassword";

 

 // 6. Set tenant name if required.

       if (!String.IsNullOrEmpty(tenantName))

 {

         TenantProviderBehavior tenantBehavior = new TenantProviderBehavior();

         tenantBehavior.TenantName = tenantName;

         channelFactory.Endpoint.Behaviors.Add(tenantBehavior);

 }

 

 // 7. Create a channel to the web service endpoint

 IThereforeService service = channelFactory.CreateChannel();

 

 // 8. Create request parameters

 GetTaskInfoParams parameters = new GetTaskInfoParams();

 parameters.TaskNo = Convert.ToInt32(txt_taskID.Text);

 

 // 9. Execute web operation

 GetTaskInfoResponse response = service.GetTaskInfo(parameters);

 

 // 10. Process response

 response.TaskInfo ...

 

 // 11. Switch communication objects into closed state.

 ((IClientChannel)service).Close();

 channelFactory.Close();

 

 

 

Windows integrated authentication:

 

 // 1. Initialize binding.

 BasicHttpBinding binding = new BasicHttpBinding();

 

 // 2. Set binding properties.

 if (useHttps)

         //for https protocol

         binding.Security.Mode = BasicHttpSecurityMode.Transport;

 else

         //for http protocol

         binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;

 

 //use windows credentials                            

 binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows;

 binding.MaxReceivedMessageSize = int.MaxValue;

 binding.ReceiveTimeout = new System.TimeSpan(0, 20, 0);

 binding.SendTimeout = new System.TimeSpan(0, 20, 0);

 

 // 3. Set server endpoint address.

 EndpointAddress endpoint = new EndpointAddress(EndpointUriSoapwin);

         

 // 4. Create a channel factory to the web service endpoint                                            

 ChannelFactory<IThereforeService> channelFactory = new ChannelFactory<IThereforeService>(binding, endpoint);

 

 // 5. Set tenant name if required.

 if (!String.IsNullOrEmpty(tenantName))

 {

         TenantProviderBehavior tenantBehavior = new TenantProviderBehavior();

         tenantBehavior.TenantName = tenantName;

         channelFactory.Endpoint.Behaviors.Add(tenantBehavior);

 }

 

 // 6. Create a channel to the web service endpoint

 IThereforeService service = channelFactory.CreateChannel();

 

 // 7. Create request parameters

 GetTaskInfoParams parameters = new GetTaskInfoParams();

 parameters.TaskNo = Convert.ToInt32(txt_taskID.Text);

 

 // 8. Execute web operation

 GetTaskInfoResponse response = service.GetTaskInfo(parameters);

 

 // 9. Process response

 response.TaskInfo ...

 

 // 10. Switch communication objects into closed state.

 ((IClientChannel)service).Close();

 channelFactory.Close();