Training for developers of X-Road interfaces Maria Kohtla

Module 4 X-Road namespace X-Road services Descriptions of services. How to find them Document templates for describing services Necessary documents

Namespace is a set or group of elements defined based on a specific naming agreement. Namespace can be declared in XML: xmlns=„http://www.nimeruumiaadress1.com“ xmlns: a=„http://www.nimeruumiaadress2.com“ XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6 Defining the alias of a namespace: xmlns:xrd=„http://x-road.ee/xsd/x-road.xsd“ xmlns:wsdl=„http://schemas.xmlsoap.org/wsdl/“ xmlns:xsd=„http://www.w3.org/2001/XMLSchema“ xmlns:id=„http://x-road.eu/xsd/identifiers“ xmlns:soap=„http://schemas.xmlsoap.org/wsdl/soap/“

Namespace XML namespace XML Schema (XSD) X-Road namespace XSD Example (http://x-road.eu/xsd/identifiers): <?xml version="1.0" encoding="UTF-8"?> <xs:schema elementFormDefault="qualified" targetNamespace="http://x-road.eu/xsd/identifiers" xmlns="http://x-road.eu/xsd/identifiers" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexType name="XRoadIdentifierType"> <xs:annotation> <xs:documentation>Globally unique identifier in the X-Road system. Identifier consists of object type specifier and list of hierarchical codes (starting with code that identifiers the X-Road instance).</xs:documentation> </xs:annotation> <xs:sequence> <xs:element minOccurs="0" ref="xRoadInstance"/> <xs:element minOccurs="0" ref="memberClass"/> <xs:element minOccurs="0" ref="memberCode"/> <xs:element minOccurs="0" ref="subsystemCode"/> <xs:element minOccurs="0" ref="groupCode"/> <xs:element minOccurs="0" ref="serviceCode"/> <xs:element minOccurs="0" ref="serviceVersion"/> <xs:element minOccurs="0" ref="securityCategoryCode"/> <xs:element minOccurs="0" ref="serverCode"/> </xs:sequence> <xs:attribute ref="objectType" use="required"/> </xs:complexType> Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6

Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6 X-Road namespaces: http://x-road.eu/xsd/identifiers http://x-road.eu/xsd/xroad.xsd http://x-road.eu/xsd/representation.xsd http://x-road.eu/xsd/x-road.xsd

Namespace Security server uses header fields: • for routing requests and responses • for validating the rights • for ensuring authenticity • for logging Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6 Header elements are necessary for providers and users of dataservice, e.g. for: • performing additional client-specific validation of rights • applying client-specific business logic calculations or filters • logging

Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6

Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road V5 header fields X-Road V6 Namespace XML namespace XML Schema (XSD) X-Road namespace X-Road v6 header fields Explanations of header fields Changes upon transfer to Version 6

Services Service in the meaning of X-Road is a predefined request-response sent by the information system of an authority (or a company) to the database and to which the database provides the agreed set of data in response. Services are technically described with a WSDL definition. In the meaning of SOAP and WSDL, service is an operation (described with a portType element) with an input and output message (described with message elements). Dataservices Metaservices Management services

Services List of service providers: http://SECURITYSERVER/listClients https://SECURITYSERVER/listClients http://SECURITYSERVER/listClients?xRoadInstance=AA Services List of central services: http://SECURITYSERVER/listCentralServices https://SECURITYSERVER/listCentralServices http://SECURITYSERVER/listCentralServices?xRoadInstance=AA Dataservices Metaservices Management services List of services: listMethods allowedMethods

Services Dataservices Metaservices Management services clientReg clientDeletion authCertReg authCertDeletion

Descriptions of services and how to find them WSDL download: http://SECURITYSERVER/wsdl https://SECURITYSERVER/wsdl xRoadInstance – X-Road set memberClass – member class memberCode – X-Road member code subsystemCode – identification code of the subsystem of the member serviceCode – service code version – service version Teenuste kirjeldused asuvad WSDL failides, mis omakorda asuvad asutuse turvaserveris, mis vastavat teenust pakub. http://10.239.255.100/wsdl?xRoadInstance=ee-dev&memberClass=COM&memberCode=11333578&subsystemCode=DEVTRAINING_10_A&serviceCode=personList&version=v1 Services list: http://x-road.eu/allmethods

Descriptions of services in RIHA Services registered on X-Road must be described also in RIHA environment (the management system of the state information system) at the address: https://riha.eesti.ee/riha/main and meet precisely the descriptions of services used in security servers

Data of dataservice Human-readable name of the service. WSDL description of the service. Functional description of the service. Security level/security class required for using the service. Conditions for provision, use and changing the service. Exploitation requirements of the service, which must include at least: operating time of the service, maximum duration of single interruption, maximum time of response to request (ensured in at least 90% responses), number of requests in a minute or number of requests per client in a minute.

Data of subsystem Data needed for describing a subsystem are described in X-Road user manual, clause 4.1 https://moodle.ria.ee/mod/page/view.php?id=288

Documents for developing dataservices X-road: Message Protocol v4.0 http://x-road.eu/docs/x-road_message_protocol_v4.0.pdf X-road: Service Metadata Protocol. Technical Specification http://x-road.eu/docs/x-road_service_metadata_protocol.pdf X-Road: Protocol for Management Services http://x-road.eu/docs/x-road_management_services_protocol.pdf X-tee rakendusjuhis https://moodle.ria.ee/mod/page/view.php?id=288 ISKE rakendusjuhend https://www.ria.ee/public/ISKE/ISKE_rakendusjuhend_8.00.pdf

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.