API - Endpoints

API Services

There are currently four services available after the API is installed - both exposing the same business functionality but with slightly different communication channels.
Please note that for development against the API - all services will require a namespace reservation as defined in the technical overview depending on your operating system.

Communication over HTTP

Single Channel HTTP (Without callback) - SOAP

The single channel http service allows communication with the Sequoia API service using SOAP messages over a http channel for maximum interoperability.

Any events that get raised by the Sequoia server side components will need to be collected by calling the appropriate service method.

By default, (unless otherwise configured), the endpoint is accessible at: http://localhost:9010/Asm/Sequoia/SequoiaApiSoapService

You are not required to authenticate with the Sequoia API to use this endpoint.

Single Channel HTTP (Without callback) - WCF

The single channel http service allows communication with the Sequoia API service using WCF SOAP messages over a http channel for interoperability.

Any events that get raised by the Sequoia server side components will need to be collected by calling the appropriate service method.

By default, (unless otherwise configured), the endpoint is accessible at: http://localhost:9010/Asm/Sequoia/SequoiaApiService

The service is provided by an endpoint that uses wsHttpBinding, a WCF (Windows communication foundation) endpoint definition which does not require a callback to be supplied on logon. You are required to authenticate with the Sequoia API to use this endpoint.

Dual Channel HTTP (With callback) - WCF

The dual channel http service allows communication with the Sequoia API service using SOAP messages over a http channel.

By default, (unless otherwise configured), the endpoint is accessible at: http://localhost:9001/Asm/Sequoia/SequoiaApiService

You are required to authenticate with the Sequoia API to use this endpoint.

The service is provided by an endpoint that uses wsDualHttpBinding, a WCF (Windows communication foundation) endpoint definition which requires a callback to be supplied on logon. This binding is less interoperable as some platforms do not support the callback.

If you are not using a .NET application and want to communicate by http, then the single channel http binding is going to be the best one for you to consume.

Any events that get raised by the Sequoia server side components will invoke the callback method specified during logon.

Communication over TCP

Two endpoints are available for communicating with the API via NET.TCP. These are to be found at port 9002 (by default) and there is one with a callback and one without.
Both need a session to be instantiated, so you must successfully call the logon method in order to make any subsequent calls.

The endpoints are (by default) at:

net.tcp://localhost:9002/Asm/Sequoia/SequoiaApiServiceWithCallback
net.tcp://localhost:9002/Asm/Sequoia/SequoiaApiServiceWithoutCallback

System.ServiceModel (WCF) Binding Configuration

As a .NET developer you will need to manually create binding configuration and reference the API contracts in order to communicate with the API via NET.TCP

A sample of binding configuration that can be used to create both channels (for the endpoints above) using the channel factory follows:

<?xml version="1.0"?>
<configuration>
  <system.serviceModel>
    <behaviors>
      <endpointBehaviors>
        <behavior name="ApiBehavior">
          <dataContractSerializer maxItemsInObjectGraph="2147483647"/>
        </behavior>
      </endpointBehaviors>
    </behaviors>

    <bindings>
      <netTcpBinding>
        <binding name="ApiTcpBinding" closeTimeout="00:10:00" openTimeout="00:10:00" receiveTimeout="Infinite" 
                 sendTimeout="00:10:00" maxConnections="10000" maxReceivedMessageSize="2147483647" maxBufferPoolSize="0" 
                 transferMode="Buffered" transactionFlow="true">
          <security mode="None"/>
          <readerQuotas maxDepth="64" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="4096" 
                        maxNameTableCharCount="65536"/>
        </binding>
      </netTcpBinding>
    </bindings>
    <client>
      <endpoint address="net.tcp://localhost:9002/Asm/Sequoia/SequoiaApiServiceWithCallback"
                behaviorConfiguration="ApiBehavior"
                binding="netTcpBinding"
                bindingConfiguration="ApiTcpBinding"
                contract="ASM.Sequoia.Api.Contracts.ServiceContracts.ISequoiaApiDualChannelService"
                name="endPointApiNetTcpWithCallback"/>

      <endpoint address="net.tcp://localhost:9002/Asm/Sequoia/SequoiaApiServiceWithoutCallback"
               behaviorConfiguration="ApiBehavior"
               binding="netTcpBinding"
               bindingConfiguration="ApiTcpBinding"
               contract="ASM.Sequoia.Api.Contracts.ServiceContracts.ISequoiaApiSingleChannelService"
               name="endPointApiNetTcpWithoutCallback"/>
    </client>
  </system.serviceModel>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>
  </startup>
</configuration>

 

Assemblies to references

Add references to the following assemblies to talk to the API:

Assembly	Description
ASM.Sequoia.API.Contracts.dll	The service and service method contracts exist in this assembly.
ASM.Sequoia.API.Common.dll	This assembly contains classes which are serializable to the API Request/Response XML specification.
System.ServiceModel	This assembly is from the .NET framework and gives you access to the channel factory.

Creating a simple application to communicate with the API via NET.TCP (No Callback)

Creating a simple method to communicate with the endpoint that does not use a callback is as simple as referencing the contracts assembly and creating a new channel factory to talk to the new endpoint.

Please note that you MUST log-in to the service using the logon() method and get a result which indicates that you have been authenticated prior to calling any other methods on the API or your application will throw an exception.

The following (C#) code uses the bindings (above) and gets the API version.

private static void SingleChannelTest()
{
    try
    {
        ChannelFactory<ISequoiaApiSingleChannelService> factory =
            new ChannelFactory<ISequoiaApiSingleChannelService>("endPointApiNetTcpWithoutCallback");

        ISequoiaApiSingleChannelService channel = factory.CreateChannel();

        SequoiaLogonResponse result = channel.Logon(new SequoiaLogonRequest { UserName = "api", Password = "api" 
        });
        Console.WriteLine(result.Authenticated ? "Logged in!" : "Did not authenticate");
        Console.WriteLine(channel.GetApiVersion().ReturnValue);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }
}

Single Channel TCP (Without callback)

Creating a simple method to communicate with the endpoint that does not use a callback is as simple as referencing the contracts assembly and creating a new channel factory to talk to the new endpoint.

Please note that you MUST log-in to the service using the logon() method and get a result which indicates that you have been authenticated prior to calling any other methods on the API or your application will throw an exception.

The following (C#) code uses the bindings (above) and gets the API version.

private static void SingleChannelTest()
{
    try
    {
        ChannelFactory<ISequoiaApiSingleChannelService> factory =
            new ChannelFactory<ISequoiaApiSingleChannelService>("endPointApiNetTcpWithoutCallback");

        ISequoiaApiSingleChannelService channel = factory.CreateChannel();

        SequoiaLogonResponse result = channel.Logon(new SequoiaLogonRequest { UserName = "api", Password =
        "api"});
        Console.WriteLine(result.Authenticated ? "Logged in!" : "Did not authenticate");
        Console.WriteLine(channel.GetApiVersion().ReturnValue);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }
}

Dual Channel TCP (With callback)

Creating a simple method to communicate with the endpoint that uses a callback is very similar to communicating the API without using a callback. The main difference is that the channel is created by the DuplexChannelFactory (rather than the ChannelFactory) and this means that you must supply a callback object.

In this example, the callback method is stored as a field (to keep it alive when the method goes out of scope) and passed into the duplex channel factory along with the endpoint name. For as long as the channel and the callback are persisted (and as long as the client application is running), the method in the callback object will be invoked whenever the API publishes any events. You can test that this is working using the following code snippet and then attaching to the API and then doing something to raise an event such as creating a Job from within Sequoia.

Please note that you MUST log-in to the service using the logon() method and get a result which indicates that you have been authenticated prior to calling any other methods on the API or your application will throw an exception.

The following (C#) code uses the bindings (above) and gets the API version.

private static ISequoiaApiServiceCallback m_SequoiaApiServiceCallback;

private static void DualChannelTest()
{
    try
    {
        m_SequoiaApiServiceCallback = new SequoiaApiServiceCallback();

        DuplexChannelFactory<ISequoiaApiDualChannelService> factory =
            new DuplexChannelFactory<ISequoiaApiDualChannelService>(m_SequoiaApiServiceCallback, 
                "endPointApiNetTcpWithCallback");

        ISequoiaApiDualChannelService channel = factory.CreateChannel();

        SequoiaLogonResponse result = channel.Logon(new SequoiaLogonRequest {UserName = "api", Password =
        "api"});
        Console.WriteLine(result.Authenticated ? "Logged in!" : "Did not authenticate");

        Console.WriteLine(channel.GetApiVersion().ReturnValue);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }
}

public class SequoiaApiServiceCallback : ISequoiaApiServiceCallback
{
    public void PublishMessage(PublishedMessage message)
    {
        Console.WriteLine(message);
    }
}