Interface architecture

About

This section describes the interface architecture against the NiP API using the back-end structure only. After the installation of NiP-API, the interfaces can be accessed through the following web services:

  • /ServiceSoap.svc

  • /ServiceRestXml.svc

  • /ServiceRestJson.svc

By default, it’s possible to access the Web Services Description Language (WSDL) file for each of the interfaces:

  • /ServiceSoap.svc?singleWsdl

  • /ServiceRestXml.svc?singleWsdl

  • /ServiceRestJson.svc?singleWsdl

Interface name

The name of the interfaces against the web services are:

  • IServiceSoap

  • IServiceRestXml

  • IServiceRestJson

Name space

The default name space of the NiP API is http://www.secmaker.com/NiP

This is used especially when sending and receiving message with XML, also known as xmlns (xml name space).

Simple Object Access Protocol (SOAP)

SOAP can be used when sending and receiving messages to or from the NiP API. The messages start with the standard SOAP Envelope declared SOAP message encoded as XML. The SOAP building blocks contains the following XML elements:

<soap:Envelope></soap:Envelope>

An envelope element that identifies the XML document as a SOAP message.

<soap:Header></soap:Header>

A header element that contains the header information.

<soap:Body></soap:Body>

A body element that contains the call and response information.

<soap:Envelope>

Every SOAP message has a root Envelope element. It must contain only one Header and Body element, and the Header element must be the first child of envelope.

<soap:Header>

There must be an action method name included inside the header element. The action must include the default name space, the name of the interface and the name of the action as a single string value of the element. The syntax of the action is:

<Action>%NameSpace%/%InterfaceName%/%ActionName%</Action>

Example 1. Action element when action method name is GetVersion
<Action>http://www.secmaker.com/NiP/IServiceSoap/GetVersion</Action>

<soap:Body>

The message of the call must be included in the body element. The message must contain the name of the method to be called. The method must include the default name space as an attribute of the element. The syntax of the call is:

<%MethodName% xmlns=”%NameSpace”></%MetodName%>

Example 2. Call message when action method name is GetVersion
<GetVersion xmlns=”http://www.secmaker.com/NiP”></GetVersion>
Example 3. SOAP request message
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
        <Action xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">
http://www.secmaker.com/NiP/IServiceSoap/GetVersion</Action>
    </soap:Header>
    <soap:Body>
        <GetVersion xmlns="http://www.secmaker.com/NiP"></GetVersion>
    </soap:Body>
</soap:Envelope>
Example 4. SOAP response message
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
        <Action xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://www.secmaker.com/NiP/IServiceSoap/GetVersion</Action>
    </soap:Header>
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <GetVersionResponse xmlns="http://www.secmaker.com/NiP">
            <GetVersionResult>
                <Version>5.3.0.10</Version>
                <Status>
                    <Code>NPR_SUCCESS</Code> (1)
                    <Description>Success</Description> (2)
                </Status>
            </GetVersionResult>
        </GetVersionResponse>
    </s:Body>
</s:Envelope>
1 Status code from the NiP API.
2 Status description from the NiP API.
In this document, all the rest of the examples will be written with the header and body elements only because the name space attributes of the xml elements are identical.