Go directly to contents.
Suomi.fi Data Exchange Layer

Meta services

This article describes the meta services provided on the security server. With meta services, you can access information about the organisations that have joined the Suomi.fi Data Exchange Layer and the services that they provide.

The purpose of meta services is to improve the discoverability of the services connected to the Data Exchange Layer and to facilitate their implementation. You can access the following information via meta services:

  • listClients: list of the organisations that have joined the Data Exchange Layer (members) and their subsystems
  • listCentralServices: list of the central services provided by the central server
  • listMethods: list of the services provided by a specific organisation
  • allowedMethods: list of the services provided by a specific organisation that the party sending the request is authorised to access
  • getWsdl: WSDL interface descriptions of the services

Meta services are available from Data Exchange Layer version 6.4 onwards. Read more about the description of the meta services protocolOpens in a new window..

Organisations that have joined the Data Exchange Layer and their subsystems (listClients)

The listClients meta service returns the list of the organisations connected to the Data Exchange Layer and their subsystems.

You can call the meta service by making a HTTP GET request on the security server:

[GET] https://{SECURITYSERVER}/listClients

In the response, the security server returns the following XML message containing the details of all organisations and subsystems connected to the Data Exchange Layer:

<ns2:clientList xmlns:ns1="http://x-
road.eu/xsd/identifiers"xmlns:ns2="http://x-road.eu/xsd/xroad.xsd">
    <ns2:member>
        <ns2:id ns1:objectType="MEMBER">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0920632-0</ns1:memberCode>
        </ns2:id>
        <ns2:name>CSC</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="MEMBER">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="SUBSYSTEM">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
            <ns1:subsystemCode>TestClient</ns1:subsystemCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="SUBSYSTEM">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
            <ns1:subsystemCode>TestService</ns1:subsystemCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
</ns2:clientList>

Services provided on the central server (listCentralServices)

The listCentralServices meta service returns the list of the central services provided on the security server of the central server

You can call the meta service by making a HTTP GET request on the security server:

[GET] https://{SECURITYSERVER}/listCentralServices

In its response, the security server returns the following XML message containing the details of the central services:

<ns2:centralServiceList
        xmlns:ns1="http://x-road.eu/xsd/identifiers"
        xmlns:ns2="http://x-road.eu/xsd/xroad.xsd">
    <ns2:centralService ns1:objectType="CENTRALSERVICE">
        <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
        <ns1:serviceCode>random</ns1:serviceCode>
    </ns2:centralService>
</ns2:centralServiceList>

Services provided by an organisation (listMethods)

The listMethods meta service returns the list of the services provided by a specific organisation.

You can call the meta service by making a SOAP call to the security server in accordance with the Data Exchange Layer communication protocol. The subsystem to which the call is addressed must be identified in the service element.

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>listMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:listMethods/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In its response, the security server returns the following list of the services specified in the call and connected to the subsystem:

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>listMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
        <xrd:requestHash 
algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">kXIWpudDipT1nlID9CvINYGJZwIxcZ0dn4LkWO9Y141M+1nJ5pDzmtR5ul+PxJnR2xDdOQBEXBgEMrodomEwfQ==
</xrd:requestHash>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:listMethodsResponse>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>helloService</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>getRandom</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
        </xrd:listMethodsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Services provided by a specific organisation that the party sending the request is authorised to access (allowedMethods)

The allowedMethods meta service returns the list of the services provided by a specific organisation that the party sending the request is authorised to access.

You can call the meta service by making a SOAP call to the security server in accordance with the Data Exchange Layer communication protocol. The subsystem to which the call is addressed must be identified in the service element.

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>allowedMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:allowedMethods/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In its response, the security server returns the list of the services that the party sending the request is authorised to access and that are connected to the subsystem specified in the call:

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>allowedMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
        <xrd:requestHash 
algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">DBtjBqBKhtoOLWzw7KeaySlNtxZ3eI9x5LR7c9974+CYdVGkPj5nqLWkcLOlwHZPlguJUeMB2sLg0URxvgaIpw==
</xrd:requestHash>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:allowedMethodsResponse>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>getRandom</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
        </xrd:allowedMethodsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Service interface descriptions (getWsdl)

The getWsdl meta service returns the WSDL description of the service specified in the call. Read more about the WSDL description used in X-Road under ‘Interface descriptions’ in the article on the X-Road communication protocol.

In HTTP POST, the connection settings specified for the subsystem making the calls are also used for the calls for meta services. In HTTP POST, SOAP messages are thus sent via the security server to the Data Exchange Layer using the standard method.

The getWsdl meta service calls is presented below.

HTTP POST request

<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xro="http://x-road.eu/xsd/xroad.xsd"
xmlns:iden="http://x-road.eu/xsd/identifiers">
    <soapenv:Header>
        <xro:protocolVersion>4.x</xro:protocolVersion>
        <xro:issue>123</xro:issue>
        <xro:id>123</xro:id>
        <xro:userId>123</xro:userId>
        <xro:service iden:objectType="SERVICE">
            <iden:xRoadInstance>FI</iden:xRoadInstance>
            <iden:memberClass>COM</iden:memberClass>
            <iden:memberCode>111</iden:memberCode>
            <iden:subsystemCode>SUB</iden:subsystemCode>
            <iden:serviceCode>getWsdl</iden:serviceCode>
            <iden:serviceVersion>v1</iden:serviceVersion>
        </xro:service>
        <xro:client iden:objectType="SUBSYSTEM">
            <iden:xRoadInstance>FI</iden:xRoadInstance>
            <iden:memberClass>COM</iden:memberClass>
            <iden:memberCode>111</iden:memberCode>
            <iden:subsystemCode>SUB</iden:subsystemCode>
        </xro:client>
    </soapenv:Header>
    <soapenv:Body>
        <xro:getWsdl>
            <xro:serviceCode>getRandom</xro:serviceCode>
            <xro:serviceVersion>v1</xro:serviceVersion>
        </xro:getWsdl>
    </soapenv:Body>
</soapenv:Envelope>

Response of the getWsdl meta service

In its response, the security server returns the WSDL description of the service specified in the call. The description also contains the descriptions of all other services described in the same WSDL. The getRandom service is specified in the example request above. The helloService is also described in the same WSDL description. For this reason, the description of the helloService is also included in the response.

When HTTP POST is used, the response (the WSDL description of requested service) is returned as an attachment to the SOAP message.

Read more about the responses and example responsesOpens in a new window..

Updated: 25/10/2024

Are you satisfied with the content on this page?