Overview

Purpose

The purpose of the OpenSRS Protocol (OPS) is to support the passing of messages between processes in the OpenSRS Architecture.

Design considerations

The OPS uses XML-based messages. By using a meta language to describe the protocol, it can remain programming language-neutral.

Any appropriate transport mechanism can be used to pass OPS protocol messages between processes, provided the message is reassembled precisely on the receiving end. Discussion of transport mechanisms is outside the scope of this document.

Process flow

When a process sends a message to another process, it generates an OPS protocol message that represents the data being sent. The OPS message is then passed to the other process, which can act on it as required and return any information that is needed (again, as a protocol message).

The generation of protocol messages is done with an API that is written for the particular programming language being used (for example, Perl or C++). The API handles the details of encoding and decoding protocol messages from and to appropriate data structures for the language being used.

Semantic validity and API implementation

Any API implementation that encodes/decodes OPS messages should be reflexive. That means that, if a message is encoded and then decoded, the results of that decoding and the original message should be identical. In other words:

MSG A := decode (encode (MSG A) )

Alternatively,

let MSG A' := encode (MSG A)
             then MSG A := decode (MSG A')

This restriction can be relaxed when it comes to the ordering of array elements and associative array elements in the OPS message. As long as the semantic meaning of the elements is preserved (semantic equivalence), the actual textual ordering in the XML stream is not important.

This is because the XML data structure representation uses element numbers (in the case of array) and field names (in the case of associative arrays) to represent the data stream, and this information can be used by the API to reconstruct the XML representation back into an in-memory data structure.

This approach supports languages in which the ordering of elements for in- memory data structures is not deterministic., for example, Perl hashes (associative arrays), where the physical ordering of elements within the hash is not guaranteed.

Example 1

The following two data blocks are considered semantically the same. Notice that the order of elements is not the same, but the key values allow the data blocks to be decoded into the same memory structure (array).

<data_block>
    <dt_assoc>
        <item key='domain_list'>
            <dt_array>
                <item key='0'>ns1.example.com</item>
                <item key='1'>ns2.example.com</item>
                <item key='2'>ns3.example.com</item>
            </dt_array>
        </item>
    </dt_assoc>
</data_block>

<data_block>
    <dt_assoc>
        <item key='domain_list'>
            <dt_array>
                <item key='2'>ns3.example.com</item>              
                <item key='0'>ns1.example.com</item>
                <item key='1'>ns2.example.com</item>
            </dt_array>
        </item>
    </dt_assoc>
</data_block>

Example 2

The following two data blocks are considered semantically the same. Notice that the order of fields is not the same, but the key values allow the data blocks to be decoded into the same memory structure (associative array).

<data_block>
    <dt_assoc>
        <item key="first_name">Tom</item>
        <item key="last_name">Jones</item>
    </dt_assoc>
</data_block>

<data_block>
    <dt_assoc>
        <item key="last_name">Jones</item>
        <item key="first_name">Tom</item>
    </dt_assoc>
</data_block>

Submitting API commands without end user credentials

You can submit API commands without specifying a username and password that is specific to the domain.

📘

Note:

The only exception is the change (password) command.

Before you can submit commands without end-user credentials, you must establish a secure connection with the OpenSRS server using a private key (use either CBC:Blowfish or HTTPS-Post). You must also include the domain parameter to identify the domain that will be affected by the command.

<?xml version="1.0" encoding="UTF-8" standalone='yes'?> 
<!DOCTYPE OPS_envelope SYSTEM 'ops.dtd'> <OPS_envelope>
<header>
<version>0.9</version>
</header>
<body>
   <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item> 
        <item key="action">modify</item> 
        <item key="object">domain</item> 
        <item key="attributes">
           <dt_assoc>
              <item key="domain">example.com</item>
              <item key="data">nexus_info</item>
              .... 
              .

Potential issues

apply_to_all flag

The apply_to_all flag is normally used to apply a change to all domains in the reseller's profile; however, you cannot use the apply_to_all flag when you submit commands without credentials. If you submit the apply_to_all flag without credentials, the command will fail.

Incorrect credentials

If end-user credentials are submitted, but they are incorrect, the command will fail.