Training for developers of X-Road interfaces Name Date

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

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.

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) <requestHash/@algorithmId> (automatically filled by the security server) http://xroad.eu/docs/x-road_message_protocol_v4.0.pdf

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.

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

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

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)

WSDL </wsdl:definitions>

<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

<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

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

<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.

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

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

Documentation elements of WSDL description Dokumentatsioonielement Kirjeldus /definitions/binding/operation/@name  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

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: https://github.com/jointxroad/components/blob/master/component_descriptions.md#x-road-wsdl-validator

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.

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.