1. Training for developers of X-Road interfaces
Name
Date

2. Structure of SOAP message
SOAP is an XML-based protocol for data exchange in distributed environments
SOAP 1.1 on X-Road
Structure of SOAP message:
Envelope determines conformity to SOAP protocol
Header enables attaching additional information
Body includes a message request or response

3. Structure of X-Road message
Elements essential for the functioning of X- Road are provided in the header of SOAP message and body data in the body of SOAP message.
Header of SOAP message is obligatory in the case of X-Road.
Messages are transmitted with UTF-8 encoding.

4. Obligatory header fields of X-Road message
<client> identifies the client having initiated the request and is described with the following elements:
xRoadInstance (EE, ee-test or ee-dev, the value of the element depends on the instance)
memberClass (member classes: GOV, COM, NGO, NEE)
memberCode (registry code of the authority)
subsystemCode (the name of the subsystem)
<service> or <centralService>
xRoadInstance, memberClass, memberCode, subsystemCode
serviceCode (the name of the wrapper corresponding to the SOAP message)
serviceVersion (dataservice version)
<id> unique identifier of the message (recommended format UUID)
<protocolVersion> (the value of the field must be 4.0)
<requestHash> (automatically filled by the security server)
(automatically filled by the security server)

5. Non-obligatory header fields of X-Road message
<userId> the value of the field is the personal identification code of the user having initiated the request together with a two-letter prefix of the ISO country code. Obligatory in the case of an authenticated end user.
<issue> the value of the field is the basis for request (internal code of the submitter of request, to indicate file, reference in document management, etc.).
A member may specify the rules for application of a non- obligatory header field in the service specification.

6. Header of X-Road Version 6
</soapenv:Header>

7. SOAP message body Response: Request: </soapenv:Body>

8. WSDL of X-Road dataservices
WSDL 1.1 documents are used for describing X-Road dataservices.
Descriptions must include the obligatory elements of X-Road.
Input and output parameters are described as an XML schema
The namespace of dataservice is not standardised on the level of the X-Road protocol (must meet XML/XSD/SOAP/WSDL standards)

9. WSDL
</wsdl:definitions>

10. <types> </xsd:element> …
          …
</xsd:schema>
<types>
Definitions of data types and elements described as XML schema
Schemas may be located inside the WSDL document, but can also be imported from outside

11. <message> </wsdl:message> Descriptions of message types
Message types are formed of the elements of XML schema described in <types> block
On X-Road, message must also be defined for describing header fields

12. <portType> </wsdl:portType>
Describes names of X-Road dataservices <operation>
Binds input and output of dataservice to the message types described in <message> blocks

13. <binding> Binding of dataservice with a message protocol
</wsdl:binding>
<binding>
Binding of dataservice with a message protocol
Document/literal wrapped style
Value of the serviceCode header field must match the name of the wrapper of input parameters of the message. E.g. personList.

14. <service> </wsdl:service>
Specific URL of dataservice is defined in the block

15. Quality of technical solution
WSDL document must be correctly structured and documented.
Only those notes must remain which may be useful for the target group (developers and analysts).
Indentation must be used in WSDL and too long lines must be avoided.
Names of elements:
Names of elements must be simple and meaningful.
Use ASCII symbols.
If dataservice has an international meaning, describe element names in English.
Import of schemas:
Use external schemas only in case the number of dataservices is high, the structure describing dataservices is very bulky, or if certain types and elements are intended to be reused.
Do not refer to a file located in a local computer or local network, because external developers cannot access it. Add imported schemas into RIHA.
Avoid double definition of elements and types of the same namespace in imported schemas.
The structure of X-Road requests must be simple and unambiguous. If abstraction of the content is necessary (binary information, files, complex alternative languages), use the pattern PM3:protocol tunnelling

16. Documentation elements of WSDL description
Dokumentatsioonielement
Kirjeldus
Code of dataservice
/definitions/portType/operation/xrd:version
Version of dataservice
/definitions/portType/operation/documentation/xrd:title 
Title of dataservice (for a user)
/definitions/portType/operation/documentation/xrd:notes 
Note of dataservice (for a user)
/definitions/portType/operation/documentation/xrd:techNotes 
Note of dataservice (for a developer)
If documentation elements are used correctly in WSDL description, MISP2 portal interface can be created based on WSDL description.
Separate XForms description is created to enable convenient use of dataservice in an instance supporting XForms technology

17. Validation rules of WSDL description and validator
Document describing X-Road dataservices must pass successfully XML as well as WSDL validation.
And conform to additional rules specified in the specification of X-Road message protocol.
WSDL validator of X-Road:

18. Versioning X-Road dataservices
Create new version of dataservice if the following conditions are met:
Updated dataservice is compatible with the original dataservice.
Provider of the service may offer the update to available users.
Available users of the service agree to use the new dataservice.
If the mentioned three conditions are not met, dataservice with new name must be created.

19. Thank You! First name Surname firstname.surname@amet.ee
The training materials for developers of X-Road interfaces have been compiled with funding from the structural funds support scheme “Raising Public Awareness about the Information Society” of the European Regional Development Fund.