6 Service Definition Library XML File for Restful services

The REST Service Definition Library XML file (ServiceDef) is the mandatory input for creating a RESTful Java EE or a PL/SQL service provider. This file should contain all the details about the Web services that need to be created.

This chapter provides a detailed description of each section of the schema as well as instructions for managing the Service Definition Library XML file.

Schema Definition

This section discusses the elements of the schema, beginning with the root element and including child elements.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1"
    xmlns="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1"
    elementFormDefault="qualified">
    <xs:element name="serviceProviderDefLibrary">

<xs:complexType>
<xs:sequence>
                <xs:element ref="service" maxOccurs="unbounded" />
            </xs:sequence>
            <xs:attribute name="appName" type="xs:string" use="required"/>
            <xs:attribute name="version" type="xs:string" use="optional" default="v1"/>
            <xs:attribute name="serviceNamespacePattern" type="xs:string" use="optional" default="http://www.oracle.com/retail/APPNAME/integration/services/SERVICENAMEService/VERSION"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="documentation" type="xs:string" />

<xs:element name="header">
<xs:complexType>
            <xs:attribute name="type" type="xs:string" use="required"/>
            <xs:attribute name="headerName" type="xs:string" use="required"/>
            <xs:attribute name="headerRequired" type="xs:boolean" use="optional" default="false"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="input">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="documentation" minOccurs="0" />
                <xs:element ref="header" minOccurs="0" maxOccurs="unbounded"  />
            </xs:sequence>
            <xs:attribute name="type" type="xs:string" use="required"/>
            <xs:attribute name="version" type="xs:string" use="optional" default="v1"/>
            <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
            <xs:attribute name="identifierNameList" type="xs:string" use="optional" />
        </xs:complexType>
    </xs:element>
    <xs:element name="output">

<xs:complexType>
<xs:sequence>
                <xs:element ref="documentation" minOccurs="0" />
                <xs:element ref="relations" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute name="type" type="xs:string" use="required"/>
            <xs:attribute name="version" type="xs:string" use="optional"  default="v1"/>
            <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
           
        </xs:complexType>
    </xs:element>
    <xs:element name="relations">

<xs:complexType>
<xs:sequence>
        <xs:element ref="relatedTo" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
   
    <xs:element name="relatedTo">
    <xs:complexType>           
        <xs:attribute name="name" use="required">
            <xs:simpleType>
                    <xs:restriction base="xs:string">
                    <xs:pattern value="[a-zA-Z0-9]*|EXTERNAL_SYSTEM"></xs:pattern>                                                                 
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
        <xs:attribute name="value" type="xs:string" use="optional" />
            </xs:complexType>
            </xs:element>

<xs:element name="fault">
<xs:complexType>
            <xs:sequence>
                <xs:element ref="documentation" minOccurs="0" />
            </xs:sequence>
            <xs:attribute name="faultType" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="operation">

<xs:complexType>
<xs:sequence>
                <xs:element ref="documentation" minOccurs="0" />
                <xs:element ref="input" />
                <xs:element ref="output" minOccurs="0" />
                <xs:element ref="fault" minOccurs="0"
                    maxOccurs="unbounded" />
            </xs:sequence>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="suffix" default="inputType">
                <xs:simpleType>
                    <xs:restriction base="xs:string">
                        <xs:enumeration value="inputType" />
                        <xs:enumeration value="outputType" />
                        <xs:enumeration value="NONE" />
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
            <xs:attribute name="operationType" default="READ_WITH_IDENTITY">
                <xs:simpleType>
                    <xs:restriction base="xs:string">
                        <xs:enumeration value="CREATE" />
                        <xs:enumeration value="READ_WITH_IDENTITY" />
                        <xs:enumeration value="READ_WITH_PREDICATE" />
                        <xs:enumeration value="UPDATE" />
                        <xs:enumeration value="DELETE" />
                        <xs:enumeration value="PROCESS" />
                    </xs:restriction>
                </xs:simpleType>
            </xs:attribute>
        </xs:complexType>
    </xs:element>
    <xs:element name="service">

<xs:complexType>
<xs:sequence>
                <xs:element ref="documentation" minOccurs="0" />
                <xs:element ref="operation" maxOccurs="unbounded" />
            </xs:sequence>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="serviceNamespace" type="xs:string" use="optional"/>
            <xs:attribute name="serviceVersion" type="xs:string" use="optional" default="v1"/>
            <xs:attribute name="custom" type="xs:boolean" use="optional" default="false"/>
        </xs:complexType>
    </xs:element>
</xs:schema>

ServiceProviderDefLibrary

This is the root element of the schema. The following is an example of the serviceProviderDefLibrary element.

Sample Rest Service Definition Library file:

<serviceProviderDefLibrary appName="rms" xmlns="http://www.oracle.com/retail/integration/services/serviceProviderDefLibrary/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<service name="Suppliers">
      <operation name="find" operationType="READ_WITH_PREDICATE" suffix="outputType">
         <input type="SupplierColRef" identifierNameList="country_id"/>
         <output type="SupplierColDesc">
         </output>
         <fault faultType="IllegalArgumentWSFaultException" />
      </operation>
      <operation name="delete" operationType="DELETE">
         <input type="SupplierColRef" identifierNameList="country_id"/>
         <output type="SupplierColRef">
         </output>
         <fault faultType="IllegalArgumentWSFaultException" />
      </operation>
     
</service>
</serviceProviderDefLibrary>

Validation rules for a service definition xml for RESTful web services

There must be a valid appName specified in service def. It must follow these rules:
- must not be empty.
- must be alphanumeric.
- must not start with a number.
There must be at least one service in the service def.
The service name must be unique in the service def.
The service name must follow these rules:
- must not be empty.
- must be alphanumeric.
- must not start with a number.
There must be at least one operation in the service.
For each operation a valid OperationType must be defined. Operation type can be one of the following:
- CREATE
- UPDATE
- DELETE
- PROCESS
- READ_WITH_IDENTITY
- READ_WITH_PREDICATE
A service must have an operation of either READ_WITH_IDENTITY or READ_WITH_PREDICATE type. If the operation type is READ_WITH_IDENTITY, then the service will generate methods to work with one object. If it operation is READ_WITH_PREDICATE, then the web service is for collection of objects.
The operation name must follow these rules:
- must not be empty.
- must be alphanumeric.
- must not start with a number.
Each operation must have a valid input type and output type defined. These types must be the names of valid payload objects.
There can be multiple methods of operation type PROCESS for a service.
A service can have either READ_WITH_IDENTITY operation or READ_WITH_PREDICATE, it cannot have both.
READ_WITH_PREDICATE operation type is only supported for CREATE and PROCESS operations. DELETE and UPDATE operations are not supported on a collection of objects.
The input type of an operation must have a valid value for the field identifierNameList, which means that the value specified for that field must follow these rules:
- It can have comma-separated names of fields.
- The fields must be valid elements present in the xsd of the payload name specified in inputType of that operation.
- If the service has an operation of type READ_WITH_PREDICATE, then the payload specified in inputType must have an element named "collection_size".That signifies that this service is for collection of objects.
The identifierNameList specified in READ_WITH_IDENTITY is used for building URI for the service. For example, if the service name is "Supplier" and identifierNameList for READ_WITH_IDENTITY operation has a value such as "supplier_id, sup_xref_key" then the URI of that service will be http://<host>:<port>/<contextPath>/SupplierResource/<supplierId>/<sup_xref_key>. An example of a request is: http://localhost:7001/rms-service/1/xref1.In this example, "1" will be substituted as the value for supplierId and "xref1" will be substituted as the value for "sup_xref_key" field.
All the operations of a service should contain the same value for identifierNameList. The identifierNameList specified in READ_WITH_IDENTITY operation is used for building the URI for UPDATE, DELETE and PROCESS methods also for the service, because the URI represents the object it is working on, and the READ_WITH_IDENTITY, DELETE, UPDATE and PROCESS methods should work on the same object.
A service can have relations sepcified in the outputType of the operation. The name specified in relatedTo element must be the name of a service which exists in the same service def xml.
A service cannot have its own name in relatedTo field