The presentation has two parts: 1. X-Road in Finland - The National Data Exchange Layer 2. REST Gateway - REST Support for X-Road

1. X-Road in Finland – The
National Data Exchange
Layer
Petteri Kivimäki
Information Systems Manager

2. Index
• National Architecture for Digital Services
• The National Data Exchange Layer
– Schedule
– Organization
– Interest Groups
– Work Groups

3. National Architecture for Digital Services
• Programme owned by Ministry of Finance
• Operating unit Finnish Population Register Centre
• Programme period 2014-2017
• Building a digital infrastructure for digital services,
including four projects:
– National Data Exchange Layer
– Service Views (Citizens, Companies, Civil Servants)
– EIdentification
– Roles and Authorization

4. National Architecture for Digital Services

5. The National Data Exchange Layer -
Schedule
31.12.
2015
1.1.
2015
1.4.
2015
1.7.
2015
1.10.
2015
29.5.
Procurement
Today
X-Road development environment, publicly openPilot
Production environment
VRK
PRH
Trafi
MML
Vero
Finto
Kela
Organizations joining
production
18.11.
Test environment
Software development
14.9.

6. Organization
Development
Manager
Pauli Kartano (VM)
Coordinating Project
Manager
Eero Konttaniemi
X-Road
Development
Product Owner
Petteri Kivimäki
Scrum Master
Developer 1 Developer 2
Speacialist
(CSC)
Developer 3
Developer 4Working Groups
Service
Production
Information
Systems Manager
Petteri Kivimäki
Service Manager
Jani-Matti
Kaukonen
Specialist 1
(CSC)
Specialist 2
(CSC)
Specialist 3
(CSC)
Gofore
Information
Security
Information
Security
Specialist
Outi Juntura
Auditors
Lawyer
(Procurements)
Palveluväylä Concept
Information Systems
Manager
Petteri Kivimäki
Service Manager
Jani-Matti
Kaukonen
Integration
Architect
(ESB:t+X-Road)
Specialist
Specialists
Project Manager
(Service
Catalogue)
Developer 1 Developer 2
Productization
Specialists
Project Manager
(Service
Management)
Specialists 2
Service Manager
Jani-Matti
Kaukonen
Working Groups
Vendors (procurements)
VRK
Valtori / Valtori’s Subcontractors
Different Interest Groups
Contractors (KPMG)

7. Responsibilities

8. Interest Groups
• Public sector
– Governmental organizations, municipalities
• Private sector
– Companies, private persons
• Other
– Associations, non-profit organizations, educational institutions
etc.

9. Work Groups
• PERTIVA – coordinates collaboration between
organizations responsible for maintaining public base
registries (e.g. population register)
• Reference groups
– For organizations that want to participate in designing the
service view for citizens and organizations
– Divided by field/industry
• Public sector organizations, tele operators, finance sector,
libraries etc.
• LinkedIn Idea Group – open for everyone
• Developer community (building up)
• And many others…

10. REST Gateway – REST
Support for X-Road
Petteri Kivimäki
Information Systems Manager

11. Index
• Backround
• Requirements for REST support
• REST Gateway

12. Backround
• REST-to-SOAP conversion must be implemented in
adapter server
• No off-to-shelf components available
• Custom implementation for each system
– Some parts are system specific, but many parts of the
implementation could be shared between different systems
– Same features are being implemented multiple times by
different organizations

13. Service Provider

14. Service Consumer

15. Requirements for REST Support
• Must have
– Access REST / JSON services via WSDL-defined X-Road
services (service provider)
– Access legacy WSDL-defined X-Road services via REST /
JSON (service consumer)
– WSDLs in the security server must match the actual service to
facilitate service discovery
• Nice to have
– Automatic conversion for service descriptions
• RAML / Swagger / JSON Schema etc. -> WSDL

16. REST Gateway
• Off-the-shelf component
– Configuration over coding
– Can be customized
• Implements the common features that are needed in
all the REST integrations
– Features can be configured for a single system / service
– Everything cannot be done through configuration, some
coding may also be required
• Offers a framework for customizations

17. REST Gateway v0.0.7

18. REST Gateway v0.0.7
• Provider Gateway
– access REST services (JSON, XML) via WSDL-defined X-
Road services
• Consumer Gateway
– access WSDL-defined X-Road services in a RESTful manner
• Automatic conversions:
– JSON -> XML
– XML -> JSON
• New REST services can be added through
configuration - no coding needed
• Implements X-Road SOAP profile 4.0 (v6.3->)

19. Provider Gateway v0.0.7
• Provider Gateway
– HTTP GET, POST, PUT and DELETE supported
– WSDL must be created manually
– REST response can be wrapped in SOAP body or SOAP
attachment
– X-Road SOAP-headers are passed via HTTP headers
• X-XRd-Client, X-XRd-Service, X-XRd-UserId, X-XRd-MessageId

20. Provider Gateway v0.0.7
• Provider Gateway accepts SOAP messages following
the X-Road SOAP profile. It translates XML request
parameters to REST service request URI.
• Configuration
FI.GOV.123456-7.TestService.getRandom.v1
=>
[GET] http://www.restservice.com/

21. Provider Gateway v0.0.7
• HTTP POST with request body
– Request body is sent as SOAP attachment identified by
Content-ID Mime header

22. Consumer Gateway v0.0.7
• Consumer Gateway
– full support for services published through Provider Gateway
– limited support for legacy services
• only services which requests don't contain nested elements - all
the request parameters must be request element's children
– HTTP GET, POST, PUT and DELETE supported
– response's content type is defined using Accept header
• text/xml, application/json
– X-Road SOAP-headers are passed via HTTP headers
• X-XRd-UserId, X-XRd-MessageId
– reformatting of resource links
– support for browser-based access

23. Consumer Gateway v0.0.7
• Consumer Gateway accepts requests, and it
translates them to SOAP messages following the X-
Road v6 SOAP profile.
• Configuration
[GET] www.restservice.com
=>
FI.GOV.123456-7.TestService.getRandom.v1

24. Consumer Gateway v0.0.7
• HTTP POST request with request body
– Request body is sent as SOAP attachment identified by
Content-ID Mime header

25. Future development
• UI for managing configuration
• Packaging
– RPM (Centos, RHEL)
– Debian (Ubuntu)
• RAML / Swagger / JSON Schema -> WSDL
conversion
• Security measures
• Message queue
• Other ideas – why not contribute?!

26. Links
• REST Gateway in GitHub
– https://github.com/educloudalliance/xroad-rest-gateway
• XRd4J – X-Road v6 Java Library
– https://github.com/petkivim/xrd4j
• Adapter Server Example
– https://github.com/petkivim/x-road-adapter-example
• Test Client
– https://github.com/petkivim/x-road-test-client
• Test Service
– https://github.com/petkivim/x-road-test-service

27. Questions?
Petteri Kivimäki
Information Systems Manager
Population Register Center
petteri.kivimaki@vrk.fi
Tel.: +358 50 593 1710