SOAP API design principles

    Version as of 05:34, 16 Jun 2019

    to this version.

    Return to Version archive.

    View current version

    This page should be guideline for everyone, who creates a new service / API function. All paterns used in Atollon SOAP API should be mentioned here so we do not solve one goal by different implementations.

     

    FILTER in listing functions

    Unified filter desing adds high value to listing function with low amount of time needed to implement.

    example

    <FILTER>
        <COL>
            <name>draftType</name>
            <type>equals</type>
            <value>1</value>
            <negation>true</negation>
        </COL>
        <COL>
    	<name>providerName</name>
    	<type>contains</type>
    	<value>Atol</value>
        </COL>
    </FILTER>
    

    Filter contains list of conditions, which defines values we want ot have in the result. Each condition consits of 4 elements.

    name - Defines which field we want to filter on. It is Enum of possible parameter names. Since we can not use Enum type (mooring request translation does not support this type) atm, write posible names into coment!

    type - Defines the type of comparision used in condition. It is an Enum of possible values. All functions does not have to implement all types of comparision, in case they do not, please mention the supported ones in documentation.

    Possible values are:

    1. equals - selected rows have to find pure match (column = value)
    2. contains - defines usage of ILIKE %value% comparision
    3. regular - request contains regular expression (not implemented yet)
    4. in - set of values (eg. usage of IDs and so) (currently implemented for comma-separated integer values only) ( =ANY(E'{value}') )
    5. range - range of values (1-100, 2016-08-23T00:00:00 - 2016-09-23T00:00:00) (not implemented yet)
    6. mask - integer bitmap mask (column & mask <> 0)
    7. less - numerical comparison (column < value)
    8. lessOrEquals - numerical comparison (column <= value)
    9. greater - numerical comparison (column > value)
    10. greaterOrEquals - numerical comparison (column >= value)

    value - string representation of value (yes, it is kinda sad that we can not verify typeon teh WSDL level, even if it is just simple int, but that is the price for the variability in minimum amount of attributes).

    negation - allows add NOT before the any type condition

     

    ORDER in listing functions

    Ordering is pretty important feature in terms of end user usage comfort. That is why every function should contain this option. I will personally find and punish every single guy, who does not use ordering enabled o client side on collections, which support the ordering!

    example

    <ORDER>
        <COL>
    	<name>created</name>
    	<desc>true</desc>
        </COL>
        <COL>
    	<name>total</name>
    	<desc>true</desc>
        </COL>
    </ORDER>
    

    name - Defines which field are we going to filter on. It is Enum of possible field names.

    desc - pretty self-explanatory, but for sure - Boolean which defines if we want to use ascending (false) or descending (true) sorting.