4.2 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 database and to which database provides an agreed set of data in response.

Services are divided into dataservices, metaservices (services for services) and management services (services to ensure operation of X-Road).

Technically, services are 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).

4.2.1 Dataservices

Dataservices are usually uniquely developed for each database and specific services of a database, enabling the use of which by information systems is the objective of X-Road. Input and output of dataservices are described in the description of services of relevant database.

4.2.2 X-Road metaservices (or validation requests)

Metaservices are support services which enable requesting information for executing dataservices, i.e. services for services. For metaservices, namespace is assigned at the address http://metadata.x-road.eu/

4.2.2.1 Overview of users and providers of metaservices

The methods which enable X-Road members to find out which dataservices are available for them and who are providing these services are described below. For this purpose, first a list must be obtained of X-Road members and subsystems, and also central services, if necessary. Then, it is necessary to contact the service providers and request the list of available dataservices.

List of service providers – clients of the security server can request a list of potential service providers. For this purpose, a HTTP GET request must be submitted to the security server http://SECURITYSERVER/listClients or https://SECURITYSERVER/listClients. Instead of the word SECURITYSERVER, the actual address of security server must be entered. Furthermore, it is possible to get a list of clients also from other affiliated X-Road sets (e.g. Finnish X-Road) by writing in the URL http://SECURITYSERVER/listClients?xRoadInstance=AA, where xRoadInstance describes X-Road set.

List of central services – clients of the security server can request a list of central services by submitting a HTTP GET request http://SECURITYSERVER/listCentralServices or https://SECURITYSERVER/listCentralServices. Instead of the word SECURITYSERVER, the actual address of the security server must be entered. Furthermore, it is possible to get a list of the central services also from other affiliated X-Road sets (e.g. Finnish X-Road) by writing in the URL http://SECURITYSERVER/listCentralServices?xRoadInstance=AA, where xRoadInstance describes X-Road set.

List of services – X-Road offers two methods (metaservices) for getting the list of services offered to an X-Road client. Both methods are challenged as regular X-Road services (see specification http://x-road.eu/docs/x-road_message_protocol_v4.0.pdf):

  • listMethods – provides the list of all services offered by the service provider;
  • allowedMethods – provides the list of all services of the service provider to which the client has an access right.

More detailed description is provided in the specification of metaservices protocol ‘X-Road: Service Metadata Protocol’ at http://x-road.eu/docs/x-road_service_metadata_protocol.pdf. The document describes methods which X-Road members can use for searching the services available for them, and obtaining WSDL files describing these services. Appendices to the specification of the protocol also include WSDL descriptions of metaservices.

4.2.2.2 History

As quite many services are still in the old version, for comparison, some metaservices which were valid in X-Road Version 5, but are no more valid in Version 6 are also described.

The following metaservices were available for the information system of an authority:

  • logOnly – the service xrd.logOnly was realised in the security server of an authority and this request was logged as an exception directly into the request log of the security server of the authority (sslog) without further transfer to any database. This enabled the information systems to use secure logging of X-Road for special purposes.

In the case of some databases, the following metaservices could be available for the information system of an authority:

  • getCharge – the service database.getCharge (where database is the name of database) could be realised in adapter server if the service provider asked changing fee for executing the service. The service returned indicated service retrieval fee for the user whose personal identification code was included in the header of request;
  • loadClassificator – the service database.loadClassificator (where database is the name of the database) could be realised in an adapter server and it issued the content of the selected classificator or its part;
  • legacyXYZ – services, the name of which had the format database.legacyXYZ (where database is the name of the database and XYZ any text characterising the service), could be realised in an adapter server and these services were considered services for entering a legacy application. Service for entering a legacy application enabled using authentication and authorisation options of the information system affiliated to X-Road in other information systems.

The following metaservice had to be realised in an adapter server:

  • listMethods – adapter server service system.listMethods returned a list of all methods offered in the adapter server. This method was intended for use only by the security server of the database.

The following metaservice could/had to be realised in an adapter server:

  • testSystem – adapter server service system.testSystem had to be realised in an adapter server if the adapter server and condition of the background system (database, etc.) had to be periodically monitored. This method was intended for use only by the security server of the database.

The following metaservices could be realised in adapter server:

  • getCharge (see description above);
  • loadClassificator (see description above);
  • legacyXYZ (see description above).

4.2.3 X-Road management services

X-Road management services are services ensuring the operation of X-Road. Management services are offered by the security server located in X-Road Center and management services enable managing security servers and X-Road members. Security servers call the services for registering configuration changes in the central server.

Management services are:

  • clientReg – registers X-Road subsystem as a client of the security server;
  • clientDeletion – removes client from the security server;
  • authCertReg – adds an authentication certificate into the security server;
  • authCertDeletion – removes an authentication certificate from the security server.

Detailed description of management services is available in the document ‘X-road: Protocol for Management Services’ at: http://x-road.eu/docs/x-road_management_services_protocol.pdf

Last modified: Monday, 8 May 2017, 3:25 PM