3.9 Quality of technical solution
All WSDL documents of X-Road should be human-readable. Therefore, a WSDL document must be correctly structured and documented. X-Road requirements set no rules for the legibility of WSDL, but following the recommendations below is a good practice for making interfacing with services easier and faster.
Upon the creation of WSDL description of dataservices, it must be always ensured that all elements, descriptions, and documentation elements have the correct UTF-8 encoding. Otherwise, problems may arise with reading the document. It often happens that texts are incorrectly encoded in documentation elements or notes. Always use tools which can perform correct processing.
Upon the creation of a service description in WSDL format, follow the following principles:
Only those notes must remain in the WSDL document which may be useful for the target group: developers and analysts dealing with the interfacing of dataservices. All unnecessary notes and code bits located inside the note must be deleted from the final version. The only exception can be descriptions in the notes of old versions of dataservices which are still used. However, even then their deletion should be considered, because generally it is always recommended to use the latest version of dataservice in the case of new interfaces.
When writing a code, indentation must be used and lines that are too long must be avoided. Some subsystems registered in RIHA use lines which are so long that some editors cannot even open the WSDL file.
- Names of elements
Names of elements must be simple and meaningful. ASCII symbols must be used in names, avoiding the use of other symbols. If dataservice has an international meaning, it is recommended to describe element names in English.
- Import of schemas
The use or non-use of external schemas may have a major impact on the legibility of WSDL, therefore it must always be carefully considered. Advantages of the use of external schemas:
makes a WSDL document compact;
enables reusing of types and elements when used by several subsystems.
Shortages of the use of external schemas:
editors cannot display imported schemas conveniently;
schemas require separate accommodation in web servers and if the web server
does not operate, it is not possible to operate with the main WSDL;
imported schemas in turn import other schemas, it is difficult to manage the
hierarchy of schemas.
Therefore, import of external schemas is recommended 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.
If it is necessary to use import of schemas, special attention should be paid to the location of imported schemas. It is not reasonable to refer to a file located in a local computer or local network, because external developers cannot access it. It is good if imported schemas are added into RIHA. This minimises the risk that imported schemas become inaccessible.
To import schemas, it is not enough to only specify the namespace in the <definitions> block of WSDL description. If elements of a schema are used inside WSDL description, <xsd:import> command must always be added into the schema located in WSDL document. For example, import of xroad schema is necessary practically in every service WSDL of X-Road, because X-Road documentation elements and X-Road headers are described in xroad schema.
Furthermore, when importing schemas, always avoid double definition of elements and types of the same namespace in imported schemas. Always consider if import is necessary at all, or all types and elements can be included in WSDL file.
In the case of schemas located in WSDL description, always try to avoid the situation where elements of the same namespace are located under several schemas. Such use of schemas is poorly specified in the WSDL standard and may cause problems in many applications.
In a perfect scenario, WSDL document should include only one schema whose namespace is the namespace of dataservice. However, if the number of types and elements is very high or schemas are intended to be reused in several different registers, import of schemas can be used.
- Unambiguous structure
The structure of X-Road requests must be simple and unambiguous. If the element <any> or type ‘anyType’ is used, it is not possible to understand clearly which request the dataservice is expecting and which response can be provided. If the content of requests or responses of dataservice cannot be strictly described, the dataservice must use attachments for transmitting such data. A strict structure of requests is necessary e.g. for MISP portals, which enables creating web interfaces based on WSDL documents. The latest version of MISP portal is MISP2, which can be applied for using X-Road dataservices in production instance as well as for testing dataservices. Further information about MISP2 portal is available at: https://github.com/jointxroad/components/blob/master/component_descriptions.md#x-road-portal-misp2.In some cases, abstraction of the content may be intentional (binary information, files, complex alternative languages). In such a case, use the pattern PM3:protocol tunnelling (https://moodle.ria.ee/mod/page/view.php?id=375).