X-Road Playground is a pre-configured X-Road environment for trying out X-Road, and it is publicly accessible to any individual and organization for free of charge. X-Road Playground provides an easy way to look into X-Road, access Security Server UIs and try out consuming and producing services.

About the Playground

X-Road Playground is a fully functional X-Road environment that consists of:

  • Central Server (CS)

  • Security Servers (SS) x3

  • Test services (IS)

  • Trust services (CA, OCSP, TSA)

  • MISP2

There are three registered member organisations in the environment:

  • NIIS - X-Road operator

  • Test company - service consumer

  • Test agency - service provider

Each organization is an owner of one Security Server in the environment.

Image 1. X-Road Playground

Image 1. X-Road Playground

Accessing Security Servers

The three Security Servers in the environment have different roles: Central Server's Security Server (1), service consumer's Security Server (2) and service provider's Security Server (3). NIIS is the owner of Security Server #1, Test company is the owner of Security Server #2 and Test agency the owner of Security Server #3. The test services are published on Security Server #3 and they can be consumed via Security Server #2.

  1. Central Server's Security Server:

  2. Service consumer's Security Server:

  3. Service provider's Security Server:

The username for the UI is "xrd", and the password is "secret".

N.B.! The credentials are read-only - it is not possible to update the Security Servers' configuration.

ACCESSING MISP2

The playground environment also hosts a connected MISP2 instance. The portal has been configured so that is is able to access the following services:

  1. Simple SOAP services:

    • PLAYGROUND:GOV:8765432-1:TestService:getRandom

    • PLAYGROUND:GOV:8765432-1:TestService:listPeople

    • PLAYGROUND:GOV:8765432-1:TestService:personDetails

  2. Simple REST services:

    • PLAYGROUND:GOV:8765432-1:TestService:getInstancesByInstanceidentifier

    • PLAYGROUND:GOV:8765432-1:TestService:getInstancesHistoryByInstanceidentifier

    • PLAYGROUND:GOV:8765432-1:TestService:getInstances

  3. A complex service example combining the listPeople and personDetails services

The web interface can be accessed from the following link: https://misp2.playground.x-road.systems/misp2

The username for the MISP2 web interface is “GBmisp”, and the password is “secret”.

N.B.! The credentials are read-only - it is not possible to update the configuration of the portal.

Trying Out Test Services

Test services are published on Security Server #3 and they can be consumed via Security Server #2. There are test services available via both SOAP and REST interfaces. Test services can be invoked in multiple ways, e.g. command line using curl, Firefox RESTClient addon.

SOAP Services

There are two test services available: getRandom and helloService. GetRandom does not take any parameters and it returns a random number between 1 and 100 (example request). HelloService takes a name as a parameter and returns a greeting with the given name (example request). The test services can be invoked through Security Server's #2 SOAP interface at:

http://testcomss01.playground.x-road.systems

SOAP requests must be submitted using HTTP POST method and content-type must be "text/xml". The examples below illustrate how the test services and listMethods meta service can be invoked using curl.

getRandom

curl -d @getRandom.xml --header "Content-Type: text/xml" -X POST http://testcomss01.playground.x-road.systems

helloService

curl -d @helloService.xml --header "Content-Type: text/xml" -X POST http://testcomss01.playground.x-road.systems

listMethods

curl -d @listMethods.xml --header "Content-Type: text/xml" -X POST http://testcomss01.playground.x-road.systems

Example requests can be downloaded at:

REST Services

REST services can be consumed using the X-Road Message Protocol for REST. X-Road Playground provides three REST APIs for testing purposes, and they each provide multiple endpoints. The APIs are public APIs providing open data, and they’re owned and maintained by third parties. Service descriptions of the APIs are available at:

The test services can be invoked through Security Server's #2 REST interface at:

http://testcomss01.playground.x-road.systems/r1/

Requests must be submitted using the HTTP method and content-type required by the endpoint to be invoked. The examples below illustrate how to invoke the test services using curl. Other available endpoints can be discovered from the service descriptions.

Suomi.fi Finnish Service Catalogue

List of organizations

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/PTV/Organization'

Details of an organization

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/PTV/Organization/97b5355c-1d74-407b-9508-452b376be153'

Finnish Trade Register’s Public Notices

List of public notices since 28th February 2019

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/TR/?totalResults=false&maxResults=10&resultsFrom=0&companyRegistrationFrom=2019-02-28'

Finnish Business Information System

List of companies registered since 28th February 2019

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/BIS?totalResults=false&maxResults=10&resultsFrom=0&companyRegistrationFrom=2019-02-28'

X-Road Simple Statistics API

List of X-Road environments

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/XRoadStatistics/instances'

Current statistics of a selected environment

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/XRoadStatistics/instances/EE'

Get API description

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.systems/r1/PLAYGROUND/GOV/8765432-1/TestService/getOpenAPI?serviceCode=XRoadStatistics'

Feedback and Questions

Please note that NIIS does not provide any support or training regarding the Playground. Please consult the X-Road documentation in case of questions. More information about the resources is available in the resources section.

Feedback and enhancement ideas regarding the Playground can be submitted to the X-Road Service Desk. Sign up for an account and get access to the X-Road Service Desk and X-Road Backlog.