JavaScript Client for CoreService

This blog post shows a way to connect to CoreService directly from a JavaScript client. The CoreService is a WCF web-service, which by default uses SOAP to communicate with its clients. However, it is quite simple to convert it into a REST service that accepts plain POST requests with parameters sent in the request body.

To keep things simple, I secured the REST endpoint with Basic auth, and thus made use of the Basic Authenticator handler over an HTTPS connection.

The Server

The WCF framework allows us to easily expose any web-service as a REST service. For this, I had to modify the file [SDLWebHome]\webservices\Web.config, and add an endpoint behavior under node <system.serviceModel> / <behaviors>. The new behavior enables endpoint to be accessible as REST service:

  <endpointBehaviors>
    <behavior name="MyJS">
      <enableWebScript />
    </behavior>
  </endpointBehaviors>

Next, because we want to use HTTPS, we define a web HTTP binding with security mode Transport, under node <system.serviceModel> / <bindings>:

  <webHttpBinding>
    <binding name="MyHttps">
      <security mode="Transport"/>
    </binding>
  </webHttpBinding>

Next, under our CoreService service definition, we add a new endpoint based on the new MyJS behavior and using the MyHttps binding. Add the following node under <system.serviceModel> / <services>:

  <service behaviorConfiguration="Tridion.ContentManager.ServiceHost.IISHost.CoreServiceBehavior"
    name="Tridion.ContentManager.ServiceHost.IISHost.CoreService201603">

    <endpoint binding="webHttpBinding" bindingConfiguration="MyHttps" behaviorConfiguration="MyJS"
      bindingNamespace="http://www.sdltridion.com/ContentManager/CoreService/201603"
      contract="Tridion.ContentManager.CoreService.ICoreService201603" address="rest" />

This configuration enables a new endpoint rest under the service CoreService201603.svc that accepts HTTPS POST requests to interact with the CoreService. Namely, the endpoint is https://web85.playground/webservices/CoreService201603.svc/rest

Even more so, the endpoint automatically generates JavaScript proxy classes based on the contract interface defined (i.e. Tridion.ContentManager.CoreService.ICoreService201603). These proxies can be used directly from the server, by loading the following script URL directly in the client web page: https://web85.playground/webservices/CoreService201603.svc/rest/js



We need to configure one last thing – we must allow cross site scripting. The client JavaScript that will consume our CoreService REST endpoint will most likely make calls to the REST endpoint from a different machine than our Content Manager. This means, we need to configure the remote IPs and the headers that are accepted to make REST calls. For example, a simple way to configure this is to add Access-Control response headers in file [SDLWebHome]\webservices\Web.config, under node <system.webServer>:

  <httpProtocol>
    <customHeaders>
      <add name="Access-Control-Allow-Methods" value="POST,OPTIONS" />
      <add name="Access-Control-Allow-Origin" value="*" />
      <add name="Access-Control-Allow-Headers" value="Authorization, Content-Type, X-Requested-With" />
    </customHeaders>
  </httpProtocol>

The Client

The JS proxies generated by the REST endpoint are readily usable, if we use the MicrosoftAjax framework. This is the easiest and quickest way to get the client application going. However, there is one big drawback – the MicrosoftAjax framework doesn’t accept any kind of security configuration when making the AJAX calls to the service (or at least I couldn’t figure it out). Our service requires Basic auth, and it seems there is no way to specify that in the MicrosoftAjax framework. Of course, one can always modify the JS source of the framework, but that would be a hack :)

In Microsoft Visual Studio (I used 2015), create a new project of type Visual C# / Web / ASP.NET Web Application. This creates all the skeleton code that is needed, including the MicrosoftAjax JS classes.

The following sample page makes a call to CoreService using the automatically generated proxy classes and MicrosoftAjax framework. Note that this code does not work OOTB in our case, because we are not sending a Basic auth request header:

<html>
<head>
    <script src="/Scripts/jquery-1.10.2.js"></script>
    <script src="/Scripts/WebForms/MSAjax/MicrosoftAjax.js"></script>
    <script src="https://web85.playground/webservices/CoreService201603.svc/rest/js"></script>
</head>
<body>
    <script>
        var service = new www.sdltridion.com.ContentManager.CoreService._201603.ICoreService();
        service.GetApiVersion(function (result) {
            alert(result);
        });
    </script>
</body>
</html>

The parameter method to GetApiVersion is a callback function that is called if the GetApiVersion invocation is a success. The response from the service is inside variable result.

Conclusion

This is a quick and elegant way of exposing a WCF service as a RESTful API without having to rewrite any server code.

The client however is not very configurable, because we can’t set an authentication method, unless we change the actual framework.

In a follow-up post, I will show a purely JQuery client that doesn’t depend or use MicrosoftAjax framework, it is much more configurable, and overall smaller in size, but we must write our skeleton proxy classes ourselves.