X-Road REST tugi

X-Roadi REST toe kohta on ilmunud üksjagu ingliskeelseid artikleid, peamiselt NIISi (Nordic Institute for Interoperability Solutions) tehnoloogiajuhi Petteri Kivimäki sulest. Soovitan huvilistel kindlasti nendega tutvuda siin: https://www.niis.org/blog-summary. Sellegipoolest pidasin vajalikuks kirjutada ka lühikese emakeelse ülevaate, mida tähendab REST tugi X-Roadil ning mida tähendab see Eesti X-tee ökosüsteemi jaoks.

Natuke ajalugu ja ülevaadet

X-Roadi REST toe analüüsi ja disainiga hakati pihta 2018. aasta kevadel, kui toimusid küsitlused ning töötoad. Esimene REST toega X-Road versioon oli 6.21.0, mis tuli välja 2019. aasta mais. Esimesel versioonil olid mõned puudused, näiteks ei toetanud see turvaserveri OpenAPI abil teenuste kirjeldamist. Täielikum REST tugi tuli 2019. aasta oktoobris versioonis 6.22.0. Selles on juba võimalik teenuseid OpenAPI 3.0 abil kirjeldada, nende pääsuõiguseid teenusekaupa hallata. Lisaks tekkis ka REST metateenuste tugi (listMethods – näita kõiki teenuseid; allowedMethods – näita lubatud teenuseid; getOpenAPI – näita teenuse OpenAPI kirjeldust).

Olulised märkused X-Roadi REST toe kohta

SOAP ja REST protokollid on paralleelsed ning tõlkimist ei toimu.
  • X-Roadi REST ja SOAP protokollid on paralleelsed ning tõlkimist ei toimu. See tähendab, et kui teenusepakkuja soovib nii REST kui SOAP teenuseid pakkuda, tuleb rakendada mõlemat.
  • REST teenuseid saab turvaserveri kaudu publitseerida, kasutades OpenAPI 3.0 kirjeldust või URLi kaupa.
  • Teenusepakkuja poolel ei vaja REST teenused täiendusi, et neid X-Roadiga liidestada.
  • Kliendi poolel üle X-Roadi REST teenuseid tarbides tuleb URLiks kasutada teenuse X-Road identifikaatorit ning lisada X-Road-Client päis.
  • Võib kasutada mis iganes tüüpi päringu keha (XML, JSON jne).

Täpse protokollikirjelduse leiab siit: https://github.com/nordic-institute/X-Road/blob/develop/doc/Protocols/pr-rest_x-road_message_protocol_for_rest.md#4-message-format.

Käed külge ehk vaatame lähemalt, kuidas X-Roadi REST tugi praktikas välja näeb

X-Road Playground

X-Road Playground (https://x-road.global/xroad-playground) on avalik, eelkonfigureeritud X-Roadi instants, kus igaüks saab serveritesse sisse logida, vaadata kasutajaliideseid ning proovida teenuste kasutamist. Seal on kaks turvaserverit, üks kliendi ja teine teenusepakkuja jaoks. 

curl -X GET -H 'X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient' -i 'http://testcomss01.playground.x-road.global/r1/PLAYGROUND/GOV/8765432-1/TestService/XRoadStatistics/instances/EE'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 16 Mar 2020 19:14:58 GMT
x-amzn-RequestId: bfba3f8e-1320-4cd4-90af-1d9f72c215f0
Access-Control-Allow-Origin: *
x-amz-apigw-id: Jf134ErGliAFpsQ=
X-Amzn-Trace-Id: Root=1-5e6fd032-111f48f9d6707fee6941f1bc;Sampled=0
X-Cache: Miss from cloudfront
Via: 1.1 2dd06bdee724b9634ae1c7344568391c.cloudfront.net (CloudFront)
X-Amz-Cf-Pop: LHR3-C1
X-Amz-Cf-Id: -z4xR3eB60A7T2iDIBHhdfQ3gnCFpykjp5iQarKBzYfO2Jrbhy5iAw==
x-road-id: PLAYGROUND-211fbfe2-6cc5-42e8-9a48-6597beeed41f
x-road-client: PLAYGROUND/COM/1234567-8/TestClient
x-road-service: PLAYGROUND/GOV/8765432-1/TestService/XRoadStatistics
x-road-request-id: d6de009b-6fa7-4e6d-bfa2-257ee31a7662
x-road-request-hash: 7QHt+NycbfDzGeYIYuC+fFlLHP6GrJk7aYmxNSy+463mtHKm3ZfAbrsvwbwEzI4aqWyNH/1xSj/wrE+J4w7ElQ==
Content-Length: 277

{"memberClasses":[{"memberClass":"GOV","memberCount":190},{"memberClass":"COM","memberCount":420},{"memberClass":"NGO","memberCount":40},{"memberClass":"NEE","memberCount":12}],"instanceIdentifier":"EE","date":"2020-03-15","subsystems":1105,"securityServers":174,"members":662}%

Võtame selle päringu tükkideks.

  • http://testcomss01.playground.x-road.global/r1/ on kliendi turvaserveri REST liides.
  • PLAYGROUND/GOV/8765432-1/TestService/XRoadStatistics/instances/EE on tarbitava teenuse identifikaator, kus PLAYGROUND on X-Road instants (X-tee toodangukeskkond on näiteks “EE”)
    • GOV on memberClass
    • 8765432-1 on memberCode (X-tee puhul tavaliselt registrikood)
    • TestService on alamsüsteemi kood
    • XRoadStatistics on teenuse kood
    • instances/EE on REST API liides, kus on öeldud, et “EE” on instants, mille kohta statistikat tahame
  • ‘X-Road-Client: PLAYGROUND/COM/1234567-8/TestClient’ on päringu päis, mis sarnaselt URLi loogikaga defineerib kliendi alamsüsteemi, mille kaudu päringu sooritame.

Muud X-Road päised tagastab teenusepakkuja turvaserver omast tarkusest, teenusepakkuja infosüsteemil pole vaja nende pärast muretseda.

Siin on turvaserveris näha teenust, mida just välja kutsusime

Standalone Security Server Docker image

Järgmine samm oleks proovida ise mõnd REST teenust X-Roadiga liidestada. Standalone Security Server Docker image [KR1] [JŠ2] (https://hub.docker.com/r/niis/xroad-security-server-standalone) on spetsiaalne turvaserveri image, mis ongi katsetamiseks mõeldud. See on eelkonfigureeritud ning pakub lihtsat viisi proovida mõnd teenust turvaserveriga liidestada. Selle kasutamiseks on vajalik, et arvutisse oleks paigaldatud Docker. Juhendi Dockeri paigaldamiseks leiab siit: https://www.docker.com/products/docker-desktop.

Laeme alla image’i ning käivitame selle.


docker pull niis/xroad-security-server-standalone
docker run -p 4000:4000 -p 80:80 --name ss niis/xroad-security-server-standalone:latest
2020-03-16 19:38:52,426 INFO exited: xroad-autologin (exit status 0; expected)

Kui see jõuab järgmise reani, saab turvaserveri kasutajaliidesesse sisse logida aadressil https://localhost:4000. Kasutajanimi on “xrd” ja parool on “secret”.

Turvaserverisse on registreeritud kaks alamsüsteemi:

  • CS/ORG/1111/TestClient
  • CS/ORG/1111/TestService

Proovime nüüd selle turvaserveriga liidestada avaliku Petstore REST API: http://petstore.swagger.io:8080/ ning seejärel teha X-Roadi kaudu päringut selle pihta.

Kõigepealt lisame TestService alamsüsteemile teenuse ja aktiveerime selle. Kasutame selleks Petstore OpenAPI 3.0 kirjeldust, mis asub siin: http://petstore.swagger.io:8080/api/v3/openapi.json.

Seejärel anname CS/ORG/1111/TestClient alamsüsteemile õiguse teenuseid kasutada. Siin saaks liideste ja meetodite kaupa õiguseid anda, aga lihtsuse huvides anname kõigele.

Nüüd on alamsüsteemil CS/ORG/1111/TestClient õigus seda teenust kasutada. Proovime ühe lemmiklooma tellimuse esitada, kasutades POST store/order teenust.

Swaggeri kaudu saame info, kuidas teenust otse välja kutsuda

curl -X POST "http://petstore.swagger.io:8080/api/v3/store/order" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"id\":10,\"petId\":198772,\"quantity\":7,\"shipDate\":\"2020-03-16T19:53:23.676Z\",\"status\":\"approved\",\"complete\":true}"

Turvaserveri kaudu päringu tegemiseks peame muutma URLi, et pöörduda turvaserveri REST liidese pihta ning defineerima seal teenuse, mille poole pöörduda. Ehk URLiks saab: 

http://127.0.0.1:80/r1/CS/ORG/1111/TestService/pets/store/order

Lisaks on meil päises vaja defineerida alamsüsteem, mille kaudu päringu sooritame:

X-Road-Client: CS/ORG/1111/TestClient

Päring ja vastus näevad välja sellised: 

curl -X POST "http://127.0.0.1:80/r1/CS/ORG/1111/TestService/pets/store/order" -H "X-Road-Client: CS/ORG/1111/TestClient" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"id\":10,\"petId\":198772,\"quantity\":7,\"shipDate\":\"2020-03-16T19:53:23.676Z\",\"status\":\"approved\",\"complete\":true}"
{"id":10,"petId":198772,"quantity":7,"shipDate":"2020-03-16T19:53:23.676+0000","status":"approved","complete":true}%

Kokkuvõte

Nagu näha, ei ole REST teenuste X-Roadiga liidestamiseks lisaarendusi vaja teha. Ka kliendi poolel on vajalikud täiendused minimaalsed.

Praegu paistab X-teel toodangukeskkonnas 4078 SOAP teenust ning 0 REST teenust (andmed siit: https://x-tee.ee/catalogue/EE) . Kas see tähendab, nüüd peaks hakkama vanu teenuseid RESTful teenusteks ümber arendama? Ei. SOAP tugi ei ole kuhugi kadumas. Siin on mõned ideed REST teenuste arendamiseks:

  • Kui planeerite uue infosüsteemi või uute teenuste arendust, siis kaaluge RESTful teenuste arendamist – need saab X-teele publitseerida lisaarendusteta ning nii teie kui ka teie klientide arendajad tänavad teid.
  • Kui teil on juba RESTful teenuseid, mis on X-teega liidestatud adapteri abil, siis kaaluge nende X-teele publitseerimist paralleelselt SOAP teenustega.
  • Suhelge oma klientidega ning uurige nende soove ja vajadusi.

Kuigi X-Road ise ei tõlgi REST ↔ SOAP sõnumeid, siis NIIS pakub lihtsat adapterit, mis piiratud kasutusjuhtudel võib hädast välja aidata: https://github.com/nordic-institute/REST-adapter-service.

Kui soovid olla rohkem kursis X-Roadi arengutega, siis selleks on mitu võimalust.

NIISi sotsiaalmeedia

NIISi GitHub

Saad ka liituda X-Road kogukonnaga

NIISi koduleht

Kui sa soovid detailsemalt infot X-Roadi kohta, siis saad luua endale konto NIISi Jiras ning jälgida sprinte

Jürgen Šuvalov
X-tee tootejuht