Connecting to Web API

BPS Web API Endpoint

BPS Web API is a SOAP based web service. It is hosted inside the SharePoint application. The web service uses basic HTTP binding and includes NTLM authentication for communication. This solution is highly flexible and can be accessed with any technology. The process of creating a client for the web service depends on what technology is used, but thanks to the WSDL file it is a rather simple operation. Pretty much any programming environment provides the tools necessary to generate a web service client classes based on a WSDL file.

BPS Web API, like all web services in SharePoint, is available in the special vti_bin folder.

The service address looks like this: http://myservername/bps_site/_vti_bin/WEBCON/Webservice_2017_1.svc Where bps_site is the site with a configured connection to the BPS database in WEBCON BPS Config feature. Designating the correct site is important, because API operations will be carried out on the BPS database set in that site’s configuration. The vti_bin folder is accessible within the context of any site, but the API will only work correctly on the site that has BPS configured.

The WSDL file address is analogous to the web service address: http://myservername/bps_site/_vti_bin/WEBCON/Webservice_2017_1.svc/mex?wsdl The WSDL file is also available in Single WSDL format. http://myservername/bps_site/_vti_bin/WEBCON/Webservice_2017_1.svc/mex?singleWsdl In this format, all contract and web service related data is collected in one file. Standard WSDL files can link to other files (like .XSD). Some tools which generate object proxy using WSDL, only work correctly when using the Single WSDL format.

Endpoints in different versions

The service and WSDL file addresses vary depending on the WEBCON BPS version. From version 7.7 to 8.2, the addresses start with: http://myservername/bps_site/_vti_bin/Webservice_8_2.svc (replace the version in the address with the desired version numbers). Starting with version 8.3, the addresses begin with (note additional WEBCON folder): http://myservername/bps_site/_vti_bin/WEBCON/Webservice_2017_1.svc

Creating web reference

Below you will find a description of how to connect with BPS Web API from a .NET application, and how to create such a reference using Visual Studio. If using other technologies this process may differ greatly, as different technologies make use of other code development tools.

Add a Service Reference to the project where you wish to use BPS Web API:

In the Address bar enter: http://myservername/bps_site/_vti_bin/WEBCON/Webservice_2017_1.svc. For the purpose of this demonstration, the server name is dev20, and the site which supports BPS is My_BPS:

Correctly adding such a reference means we have access to the web service and can invoke it at will.

After creating the Service Reference a new class is created for the web service client: BPSWebserviceClient, as well as new entries in app.config detailing connection parameters to the newly created reference. In order for the web service client to work correctly, configure the service binding for the connection and enter the correct web service address.

Enforcing proper endpoint address

For web services hosted in SharePoint, WSDL files are generated automatically by an appropriate factory in SharePoint. It is worth mentioning that the factory always generates the same endpoint address in the WSDL file. The SharePoint address (site) from which the WSDL file is downloaded, is irrelevant. The WSDL file will always contain the endpoint address of the web service within the context of a root site. In our case, even though we want to use the web service under the address: http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc And the following WSDL file is used to create the service reference: http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc/mex?wsdl The following endpoint address will be found inside the WSDL file: http://dev20/_vti_bin/WEBCON/Webservice_2017_1.svc

This address will also be entered into the app.config file when creating a service reference. Notice that the part of the address which designates the site – My_BPS is omitted. This fact is important, since it is the site that contains information on which database BPS API should operate on.

To remedy this, in app.config, manually change all endpoint addresses. Alternatively, when creating a new instance of the class: BPSWebserivceClient, you can pass on the correct address, containing the site, as a second parameter of the constructor. Like so:

// Set correct endpoint address
var client = new BPS_Webservice_2017_1.BPSWebserviceClient(
    "BasicHttpBinding_BPSWebservice", 
    "http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc");

Binding configuration using app.config file

The next necessary step is to correctly set security in the bindings configuration. In SharePoint, when adding a service reference, 3 bindings are automatically generated in the app.config file. The default http binding, anonymous access binding and a NTLM authentication binding. Each has a different configuration and a different addresses.

You should connect to the API through the default address (without the NTLM suffix or anonymous), but the security configuration must be identical to NTLM authentication (as Web API uses NTLM authentication). For this reason, in the configuration, find the binding which connects to the address: http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc In the security configuration for this binding, add settings suitable for NTLM authentication.

<binding name="BasicHttpBinding_BPSWebservice">
  <security mode="TransportCredentialOnly">
    <transport clientCredentialType="Ntlm" />
  </security>
</binding>

Below is the whole content of app.config file for our example after the described modifications. Changes had to be made to the binding named BasicHttpBinding_BPSWebservice

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <bindings>
            <basicHttpBinding>
                <binding name="BasicHttpBinding_BPSWebservice" />
                <binding name="BasicHttpBinding_BPSWebservice1" />
                <binding name="BasicHttpBinding_BPSWebservice2">
                    <security mode="TransportCredentialOnly">
                        <transport clientCredentialType="Ntlm" />
                    </security>
                </binding>
            </basicHttpBinding>
        </bindings>
      <client>
        <endpoint address="http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc"
          binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_BPSWebservice"
          contract="BPS_Webservice_2017_1.BPSWebservice" name="BasicHttpBinding_BPSWebservice" />
        <endpoint address="http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc/anonymous"
          binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_BPSWebservice1"
          contract="BPS_Webservice_2017_1.BPSWebservice" name="BasicHttpBinding_BPSWebservice1" />
        <endpoint address="http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc/ntlm"
          binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_BPSWebservice2"
          contract="BPS_Webservice_2017_1.BPSWebservice" name="BasicHttpBinding_BPSWebservice2" />
      </client>
    </system.serviceModel>
</configuration>

After these changes, connecting the web service BPS API should now work as intended. Make sure when creating the class: BPSWebserwviceClient, that the first parameter of the constructor is a correct binding name. Additionally, in the client class, set the ClientCredential and AllowedImpersonationLevel properties to suitable values.

// Set correct endpoint address
var client = new BPS_Webservice_2017_1.BPSWebserviceClient(
    "BasicHttpBinding_BPSWebservice", 
    "http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc");
// Set the ClientCredential and AllowedImpersonationLevel properties
client.ClientCredentials.Windows.ClientCredential = 
    System.Net.CredentialCache.DefaultNetworkCredentials;
client.ClientCredentials.Windows.AllowedImpersonationLevel = 
    System.Security.Principal.TokenImpersonationLevel.Impersonation

Binding configuration using .NET code

In the case that we do not want to use binding settings stored in app.config, we can set these settings using .NET code instead. For that to work however, apart from creating a client class and setting ClientCredential and AllowedImpersonationLevel properties, it is also necessary to configure the binding using the class: BasicHttpBinding.

// Set correct endpoint address
var client = new BPS_Webservice_2017_1.BPSWebserviceClient(
    "BasicHttpBinding_BPSWebservice", 
    "http://dev20/My_BPS/_vti_bin/WEBCON/Webservice_2017_1.svc");
// Set the ClientCredential and AllowedImpersonationLevel properties
client.ClientCredentials.Windows.ClientCredential = 
    System.Net.CredentialCache.DefaultNetworkCredentials;
client.ClientCredentials.Windows.AllowedImpersonationLevel = 
    System.Security.Principal.TokenImpersonationLevel.Impersonation;
// Binding configuration - NTLM
var binding = new BasicHttpBinding();
binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Ntlm;
client.Endpoint.Binding = binding;