X-Road-tiedonsiirtoprotokolla

Tällä sivulla kuvataan Suomi.fi-palveluväylän X-Road-tiedonsiirtoprotokolla.

Palveluväylään liittyminen edellyttää, että liitettävä järjestelmä pystyy lähettämään ja vastaanottamaan SOAP- ja REST-sanomia X-Roadin edellyttämässä muodossa. Käytännössä tämä tarkoittaa sitä, että SOAP- ja REST-sanomien tulee sisältää tietyt X-Road-tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan X-Road-protokollan määrittelemällä tavalla. X-Roadin versio 7 käyttää SOAP-versiota 1.1.

Sivulla esitellään:

1. X-Road-viestiprotokolla SOAPille. Lue lisää X-Roadin protokollakuvauksesta SOAPille (englanniksi)Avautuu uuteen ikkunaan..
2. X-Road-viestiprotokolla RESTille. Lue lisää X-Roadin protokollakuvauksesta RESTille (englanniksi)Avautuu uuteen ikkunaan..

1. X-Road-viestiprotokolla SOAPille

HTTP-otsikkotiedot

X-Road edellyttää taulukossa 1 esitettyjen HTTP-otsikkotietojen käyttöä sen kautta lähetetyissä sanomissa. Liitteitä sisältävissä sanomissa Content-Type-otsikkotiedon on oltava multipart/related, muutoin on käytettävä arvoa text/xml. SOAPAction-otsikkotietokentän voi jättää tyhjäksi, tai sen voi määritellä osoittamaan haluttuun URI-määritykseen.

Taulukko 1. HTTP-otsikkotiedot.

*) Liityntäpalvelin säilyttää ja välittää SOAPAction-otsikkotietueen palvelulle X-Roadin versiosta 6.16.0 lähtien. Validi URI tarkoittaa, että URI on määritelty heittomerkkien sisään (liityntäpalvelinohjelmisto tarkistaa tämän).

Esimerkki oikein määritellystä SOAPAction-otsikkotiedosta:

SOAPAction: "http://x-road.eu/app#MyMessage"

Esimerkki oikein määritellystä tyhjästä arvosta SOAPAction-otsikkotiedossa:

SOAPAction: ""

Rajapintakuvaukset

X-Road edellyttää siihen liitettävien palveluiden kuvaamista WSDL-kielellä. Kysely- ja vastaussanomien rakenteen kuvaavat XML-skeemat voidaan joko sisällyttää suoraan WSDL-kuvaukseen tai kuvata erillisissä XML Schema Definition (XSD) -tiedostoissa. Näihin XSD-tiedostoihin viitataan WSDL-kuvauksessa import-määrityksen avulla.

XSD-tiedostoja käytettäessä pitää huomioida, että xml:include ei toimi, koska käyttäjällä ei ole pääsyä WSDL:n tarjoajan tietojärjestelmään. Sen sijaan xml:import toimii, mutta XSD-tiedosto pitää tarjota julkiseen internetiin ja importissa pitää antaa absoluuttinen osoite eikä vain relatiivista osoitetta.

Esimerkiksi tämä on oikea tapa:

<xsd:import namespace="xyz" schemaLocation="http://palvelu-x.yritys.com/model.xsd"/>

Tämä taas on väärä tapa:

<xsd:import namespace="xyz" schemaLocation="model.xsd/>

Skeemoissa tulee käyttää nimiavaruuksia ja yksiselitteisiä nimiä elementeille. WSDL-kuvauksessa käytettyjen datatyyppien täytyy löytyä nimiavaruuksien määrittämistä verkkosijainneista; muuten WSDL:n importtaus epäonnistuu liityntäpalvelimella. Tämä on huomioitava erityisesti siinä tapauksessa, että käytettävät nimiavaruudet eivät ole yleisesti julkisessa internetissä saatavilla olevia, vaan ne on tehty esimerkiksi vain tiettyä, suljettua tarkoitusta varten. Tällöin nimiavaruus pitää tarjota julkiseen internetiin, jotta sen käyttö on mahdollista.

Skeemoissa on suositeltavaa käyttää elementFormDefault=”qualified”-määritystäAvautuu uuteen ikkunaan.. Sen mukaan kaikkien kyseiseen XML-skeemaan perustuvissa sanomissa käytettävien elementtien tulee täyttää skeemassa määritellyissä nimiavaruuksissa asetetut vaatimukset. Käytännössä sanomissa ei siis saa olla elementtejä, joita ei ole määritelty skeemassa tai skeeman käyttämissä nimiavaruuksissa. Tällä tavoin ehkäistään nimikonfliktien syntyminen ja varmistetaan, että jokainen elementti on yksilöitävissä yksiselitteisesti.

WSDL-dokumentissa on käytettävä document/literal-sidontaa (binding style=”document”; use=”literal”). Palvelukutsujen sidontatyylin (binding style) on oltava ‘document’. Use-attribuutin arvon on puolestaan oltava ‘literal’.

Palveluväylän WSD-esimerkki ilman request-response-kääreitä (XML, 7,31 kt)Avautuu uuteen ikkunaan.

Palveluväylän WSDL-esimerkki request-response-kääreitä käytettäessä (XML, 8,86 kt)Avautuu uuteen ikkunaan.

Seuraavassa on esimerkki WSDL-tiedostosta, jossa esitellään getRandom-palvelu:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://test.x-road.fi/producer"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:id="http://x-road.eu/xsd/identifiers"
                  name="testService" targetNamespace="http://test.x-road.fi/producer">
    <wsdl:types>
        <xsd:schema elementFormDefault="qualified" targetNamespace="http://test.x-road.fi/producer">
            <!-- Import X-Road schema -->
            <xsd:import id="xrd" namespace="http://x-road.eu/xsd/xroad.xsd" schemaLocation="http://x-
road.eu/xsd/xroad.xsd"/>
            <xsd:element name="getRandom" nillable="true">
                <xsd:complexType />
            </xsd:element>
            <xsd:element name="getRandomResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="data" type="xsd:string">
                            <xsd:annotation>
                                <xsd:documentation>
                                    Service response
                                </xsd:documentation>
                            </xsd:annotation>
                        </xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="requestheader">
        <wsdl:part name="client" element="xrd:client" />
        <wsdl:part name="service" element="xrd:service" />
        <wsdl:part name="userId" element="xrd:userId" />
        <wsdl:part name="id" element="xrd:id" />
        <wsdl:part name="issue" element="xrd:issue"/>
        <wsdl:part name="protocolVersion" element="xrd:protocolVersion" />
    </wsdl:message>
    <wsdl:message name="getRandom">
        <wsdl:part name="body" element="tns:getRandom"/>
    </wsdl:message>
    <wsdl:message name="getRandomResponse">
        <wsdl:part name="body" element="tns:getRandomResponse"/>
    </wsdl:message>
    <wsdl:portType name="testServicePortType">
        <wsdl:operation name="getRandom">
            <wsdl:input message="tns:getRandom"/>
            <wsdl:output message="tns:getRandomResponse"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="testServiceBinding" type="tns:testServicePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="getRandom">
            <soap:operation soapAction="" style="document" />
            <xrd:version>v1</xrd:version>
            <wsdl:input>
                <soap:body parts="body" use="literal"/>
                <soap:header message="tns:requestheader" part="client" use="literal"/>
                <soap:header message="tns:requestheader" part="service" use="literal"/>
                <soap:header message="tns:requestheader" part="userId" use="literal"/>
                <soap:header message="tns:requestheader" part="id" use="literal"/>
                <soap:header message="tns:requestheader" part="issue" use="literal"/>
                <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body parts="body" use="literal"/>
                <soap:header message="tns:requestheader" part="client" use="literal"/>
                <soap:header message="tns:requestheader" part="service" use="literal"/>
                <soap:header message="tns:requestheader" part="userId" use="literal"/>
                <soap:header message="tns:requestheader" part="id" use="literal"/>
                <soap:header message="tns:requestheader" part="issue" use="literal"/>
                <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="testService">
        <wsdl:port binding="tns:testServiceBinding" name="testServicePort">
            <soap:address location="http://example.com/Endpoint"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

WSDL:n alussa esitellään tarvittavat namespacet. HUOM! Käytä aina absoluuttista osoitetta.

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://test.x-road.fi/producer"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:id="http://x-road.eu/xsd/identifiers"
                  name="testService" targetNamespace="http://test.x-road.fi/producer">

Tarjottujen operaatioiden tietotyypit:

<wsdl:types>
    <xsd:schema elementFormDefault="qualified" targetNamespace="http://test.x-road.fi/producer">
        <!-- Import X-Road schema -->
        <xsd:import id="xrd" namespace="http://x-road.eu/xsd/xroad.xsd" schemaLocation="http://x-
road.eu/xsd/xroad.xsd"/>
       <xsd:element name="getRandom" nillable="true">
       <xsd:complexType />
            </xsd:element>
            <xsd:element name="getRandomResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="data" type="xsd:string">
                            <xsd:annotation>
                                <xsd:documentation>
                                    Service response
                                </xsd:documentation>
                            </xsd:annotation>
                        </xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
        </xsd:element>
    </xsd:schema>
</wsdl:types>

X-Road-parametrit pyynnön otsikko-osaan:

<wsdl:message name="requestheader">
    <wsdl:part name="client" element="xrd:client" />
    <wsdl:part name="service" element="xrd:service" />
    <wsdl:part name="userId" element="xrd:userId" />
    <wsdl:part name="id" element="xrd:id" />
    <wsdl:part name="issue" element="xrd:issue"/>
    <wsdl:part name="protocolVersion" element="xrd:protocolVersion" />
</wsdl:message>

Tarjottavan palvelun sisältö. Rakenteen pitää aina olla seuraavanlainen:

<wsdl:message name="getRandom">
    <wsdl:part name="body" element="tns:getRandom"/>
</wsdl:message>
<wsdl:message name="getRandomResponse">
    <wsdl:part name="body" element="tns:getRandomResponse"/>
</wsdl:message>

Tarjottava operaatio:

<wsdl:portType name="testServicePortType">
    <wsdl:operation name="getRandom">
        <wsdl:input message="tns:getRandom"/>
        <wsdl:output message="tns:getRandomResponse"/>
    </wsdl:operation>
</wsdl:portType>

Tarjottavan operaation esittely. Input body sisältää itse kyselyn operaatiolle, ja headerit ohjaavat kyselyn oikealle servicelle. Output bodyssa on operaation vastaus ja edelleen service, jolle kysely oli tullut.

<wsdl:binding name="testServiceBinding" type="tns:testServicePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
    <wsdl:operation name="getRandom">
        <soap:operation soapAction="" style="document" />
        <xrd:version>v1</xrd:version>
        <wsdl:input>
            <soap:body parts="body" use="literal"/>
            <soap:header message="tns:requestheader" part="client" use="literal"/>
            <soap:header message="tns:requestheader" part="service" use="literal"/>
            <soap:header message="tns:requestheader" part="userId" use="literal"/>
            <soap:header message="tns:requestheader" part="id" use="literal"/>
            <soap:header message="tns:requestheader" part="issue" use="literal"/>
            <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts="body" use="literal"/>
            <soap:header message="tns:requestheader" part="client" use="literal"/>
            <soap:header message="tns:requestheader" part="service" use="literal"/>
            <soap:header message="tns:requestheader" part="userId" use="literal"/>
            <soap:header message="tns:requestheader" part="id" use="literal"/>
            <soap:header message="tns:requestheader" part="issue" use="literal"/>
            <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

Sen servicen koko nimi, joka tarjoaa yllä mainitut operaatiot:

<wsdl:service name="testService">
    <wsdl:port binding="tns:testServiceBinding" name="testServicePort">
        <soap:address location="http://example.com/Endpoint"/>
    </wsdl:port>
</wsdl:service>

SOAP-otsikkotiedot

X-Roadin edellyttämät SOAP-otsikkotiedot on esitetty taulukossa 2.

Taulukko 2. SOAP-otsikkotiedot.

Vastaussanoman tulee sisältää täsmälleen samat otsikkotiedot kuin kyselysanomassakin on.

Palvelun hyödyntäjän (consumer) ilmaisemiseen käytetään client-elementtiä ja tuottajan (producer) ilmaisemiseen service-elementtiä. Molemmat elementit koostuvat useista alielementeistä, joiden sisällöistä hyödyntäjän ja tuottajan yksilöivät tunnisteet muodostuvat:

• organisaatiokohtaiset tunnisteet: sdsbInstance, memberClass, memberCode
• järjestelmäkohtaiset tunnisteet: xRoadInstance, memberClass, memberCode, subsystemCode
• palvelukohtaiset tunnisteet: xRoadInstance, memberClass, memberCode, subsystemCode, getRandom, serviceVersion.

Alla olevan esimerkkisanoman tapauksessa hyödyntäjän tunniste on FI.GOV.12345-6.ConsumerService ja tuottajan tunniste FI.GOV.65432-1.DemoService.getRandom.v1.

Otsikkotiedot versiossa 6:

<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">
  <soapenv:Header>  
    <xrd:client id:objectType="SUBSYSTEM">
      <id:xRoadInstance>FI</id:xRoadInstance>
      <id:memberClass>GOV</id:memberClass>
      <id:memberCode>12345-6</id:memberCode>
      <id:subsystemCode>ConsumerService</id:subsystemCode>
    </xrd:client>
    <xrd:service id:objectType="SERVICE">
      <id:xRoadInstance>FI</id:xRoadInstance>
      <id:memberClass>GOV</id:memberClass>
      <id:memberCode>65432-1</id:memberCode>
      <id:subsystemCode>DemoService</id:subsystemCode> 
      <id:serviceCode>getRandom</id:serviceCode>
      <id:serviceVersion>v1</id:serviceVersion>
    </xrd:service>
    <xrd:userId>mvirtanen</xrd:userId>
    <xrd:id>1234567890</xrd:id>       
    <xrd:protocolVersion>4.0</xrd:protocolVersion>
  </soapenv:Header>
  <soapenv:Body>
    .
    .
    .
  </soapenv:Body>
</soapenv:Envelope>

Taulukossa 3 on esitetty lyhyet kuvaukset client- ja service-elementtien alielementtien sisällöistä.

Taulukko 3. Client- ja service-elementit.

Lue lisää X-Roadin käyttämistä tunnisteista.

SOAP Body

Palveluväylään liitettävän tietojärjestelmän käyttämät kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan X-Road-protokollan määrittelemällä tavalla. X-Roadin versiosta 6 lähtien request-/response-kääreiden käyttö ei ole enää pakollista.

Palveluväylään liittyvät organisaatiot saavat itse päättää request-/response-kääreiden käytöstä omien palveluidensa Palveluväylä-liitosten toteutuksissa. Kääreiden käytön on kuitenkin oltava yhdenmukaista yksittäisen palvelun kohdalla. Kääreitä tulee siis käyttää sekä kysely- että vastaussanomissa tai ei kummassakaan.

Kyselysanoma

X-Roadin kautta lähetettävien kyselysanomien (request) on oltava seuraavanlaisia, kun request-/response-kääreitä ei käytetä:

Palveluväylän kyselysanoma, esimerkki ilman request-response-kääreitä (XML, 1,22 kt)Avautuu uuteen ikkunaan.

<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">
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:service xmlns:m="URI">
        Request content
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Request-/response-kääreitä käytettäessä taas kyselysanoman pitää olla seuraavanlainen:

Palveluväylän kyselysanoma, esimerkki request-response-kääreitä käytettäessä (XML, 1,31 kt)Avautuu uuteen ikkunaan.

<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">
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:service xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Kyselysanoman hyötykuorma

Kyselysanoman hyötykuorma (payload) tulee sijoittaa SOAP-sanoman body-osaan. Hyötykuorman sisältävä XML-elementti on nimettävä palvelun mukaan. Palvelun nimi on määritelty SOAP-sanoman otsikkotiedoissa service-elementin alla sijaitsevassa serviceCode-elementissä.

Seuraavassa esimerkissä on esitetty helloService-palvelun kutsu ilman request-käärettä. Siitä on selvyyden vuoksi jätetty pois kaikki ylimääräiset elementit.

<SOAP-ENV:Envelope> 
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloService xmlns:m="URI">
        Request content
    </m:helloService>
  </soapenv:Body>
</soapenv:Envelope>

Katso myös yksinkertaistamattomat kyselysanomat:

Kuva: yksinkertaistamaton helloService-palvelun kutsu ilman request-käärettä

Näytä kuva suurempana

Kuva: yksinkertaistamaton helloService-palvelun kutsu request-käärettä käytettäessä

Näytä kuva suurempana

Vastaussanoma

X-Roadin kautta lähetettävien vastaussanomien tulee aina sisältää samat otsikkotiedot kuin kyselysanomassakin on.

X-Roadin kautta lähetettävien vastaussanomien (response) on oltava muodoltaan seuraavanlaisia, kun request-/response-kääreitä ei käytetä:

<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">
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:serviceResponse xmlns:m="URI">
        Response content
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Request-/response-kääreitä käytettäessä vastaussanoman pitää olla seuraavanlainen:

<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">
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:serviceResponse xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
      <m:response>
        Response content
      </m:response>
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Katso myös yksinkertaistamattomat vastaussanomat:

yksinkertaistamaton vastaussanoma ilman request-response-käärettä (XML, 1,28 kt)Avautuu uuteen ikkunaan.

yksinkertaistamaton vastaussanoma request-response-käärettä käytettäessä (XML, 1,43 kt)Avautuu uuteen ikkunaan.

Vastaussanoman hyötykuorma

Vastaussanoman hyötykuorma (payload) tulee sijoittaa SOAP-sanoman body-osaan. Hyötykuorman sisältävä XML-elementti on nimettävä siten, että elementin nimi muodostuu palvelun nimestä ja nimen perään lisättävästä Response-liitteestä. Palvelun nimi on määritelty SOAP-sanoman otsikkotiedoissa service-elementin alla sijaitsevassa serviceCode-elementissä.

Alla on esitetty helloService-palvelun palauttamat vastaussanomat. Niistä on selvyyden vuoksi jätetty pois kaikki ylimääräiset elementit.

Esimerkki ilman request-/response-kääreitä:

<SOAP-ENV:Envelope>
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloServiceResponse xmlns:m="URI">
        Response content
    </m:helloServiceResponse>
  </soapenv:Body>
</soapenv:Envelope>

Esimerkki request-/response-kääreitä käytettäessä:

<SOAP-ENV:Envelope>
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloServiceResponse xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
      <m:response>
        Response content
      </m:response>
    </m:helloServiceResponse>
  </soapenv:Body>
</soapenv:Envelope>

Katso myös yksinkertaistamattomat vastaussanomat:

yksinkertaistamaton helloService-palvelun vastaussanoma ilman request-/response-käärettä

Kuva: yksinkertaistamaton helloService-palvelun vastaussanoma ilman request-response-käärettä

Näytä kuva suurempana

yksinkertaistamaton hello-Service-palvelun vastaussanoma request-/response-käärettä käytettäessä.

Kuva: yksinkertaistamaton hello-Service-palvelun vastaussanoma request-response-käärettä käytettäessä

Näytä kuva suurempana

Virhesanomat

X-Road mahdollistaa kahdentyyppisten virhesanomien palauttamisen: standard SOAP error ja non-technical SOAP error.

Standard SOAP error

SOAP-otsikkotietojen sisällyttäminen standard SOAP error -virhesanomaan ei ole pakollista, mutta se on suositeltavaa. Virhekoodeina (fault code) tulee käyttää SOAP-määritysten mukaisia virhekoodejaAvautuu uuteen ikkunaan.:

VersionMismatch

• SOAP-viestissä on käytetty virheellistä nimiavaruutta. Tästä syystä SOAP-käsittelijä generoi virhekoodin versioiden yhteensopimattomuudesta. Katso tarkemmin, miten nimiavaruuden pitää olla määritetty.

MustUnderstand

• SOAP-otsikkoelementin lapsielementti sisältää MustUnderstand-attribuutin arvolla TRUE tai 1, mutta viestin vastaanottajan SOAP-käsittelijä ei pysty tunnistamaan tai käsittelemään elementtiä.

Client

• Client-virhekoodilla viitataan kutsusanoman virheelliseen sisältöön. Tällöin asiakaspään muodostama kutsusanoma on virheellinen.

Server

• Server-virhekoodilla viitataan muihin kuin kutsusanoman sisällön aiheuttamiin virhetilanteisiin. Tällöin kutsun käsittelyssä on sattunut virhe palvelun puolella.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>fault code</faultcode>
            <faultstring>fault string</faultstring>
            <faultactor>fault actor</faultactor>
            <detail>fault details</detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Non-technical SOAP error

Non-technical SOAP error on sovelluskohtainen virhesanoma. Sen tulisi sisältää sovelluskohtainen virhekoodi (fault code) ja virhekuvaus (fault string). Sanomaan tulee sisällyttää SOAP-otsikkotiedot.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <m:serviceResponse xmlns:m="URI">
            <faultCode>fault code</faultCode>
            <faultString>fault string</faultString>
        </m:serviceResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Non-technical SOAP error -virhesanomassa voidaan käyttää request-/response-kääreitä tavallisen vastaussanoman tapaan. Jos kääreet ovat käytössä kysely- ja vastaussanomissa, niitä tulisi käyttää myös non-technical SOAP error -virhesanomassa.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <m:serviceResponse xmlns:m="URI">
            <m:request>
                Request content
            </m:request>
            <m:response>
                <faultCode>fault code</faultCode>
                <faultString>fault string</faultString>
            </m:response>
        </m:serviceResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Esimerkkipalvelu

Esimerkki ilman request-/response-kääreitä

Esimerkkinä käytetään yksinkertaista helloService-palvelua. Sille annetaan kyselysanoman parametrina käyttäjän nimi ja palautetaan vastaussanomassa kyseiselle käyttäjälle osoitettu tervehdys.

Katso palveluun liittyvät esimerkit:

Palveluväylän esimerkkipalvelu, rajapintakuvaus ilman kääreitä (XML, 7,31 kt)Avautuu uuteen ikkunaan.

Palveluväylän esimerkkipalvelu, kutsusanoma ilman kääreitä (XML, 1,22 kt)Avautuu uuteen ikkunaan.

Palveluväylän esimerkkipalvelu, vastaussanoma ilman kääreitä (XML, 1,28 kt)Avautuu uuteen ikkunaan.

Esimerkki request-/response-kääreiden kanssa

Esimerkkinä käytetään yksinkertaista helloService-palvelua. Sille annetaan kyselysanoman parametrina käyttäjän nimi ja palautetaan vastaussanomassa kyseiselle käyttäjälle osoitettu tervehdys.

Katso palveluun liittyvät esimerkit:

Palveluväylän esimerkkipalvelu, rajapintakuvaus kääreiden kanssa (XML, 8,86 kt)Avautuu uuteen ikkunaan.

Palveluväylän esimerkkipalvelu, kutsusanoma kääreiden kanssa (XML, 1,31 kt)Avautuu uuteen ikkunaan.

Palveluväylän esimerkkipalvelu, vastaussanoma kääreiden kanssa (XML, 1,43 kt)Avautuu uuteen ikkunaan.

2. X-Road-viestiprotokolla RESTille

REST toimii SOAP-sanomien rinnalla. Tutustu RESTin X-Road-viestiprotokollan yksityiskohtiin (englanniksi)Avautuu uuteen ikkunaan., kuten valinnaisiin otsikkotietoihin.

HTTP-otsikkotiedot

RESTiä käytettäessä kutsujalla on vain yksi pakollinen otsikkotieto, X-Road-Client. Muut otsikkotiedot ovat valinnaisia. X-Road-Client määrittää organisaation/alijärjestelmän, joka toimii palvelun kutsujana. Alijärjestelmän koodi on valinnainen.

X-Road-Client: INSTANCE/CLASS/MEMBER/SUBSYSTEM

X-Road-liityntäpalvelin ylikirjoittaa aina seuraavat otsikkotiedot:

• Connection
• Host
• Keep-Alive
• Proxy-Authenticate
• Proxy-Authorization
• Server
• TE
• Trailer
• Transfer-Encoding
• Upgrade
• User-Agent.

Kyselysanoma

X-Road käyttää HTTP-versiota 1.1. Organisaatio/alijärjestelmä määritellään käyttämällä HTTP-otsikkotietoja. Kutsuttava järjestelmä on enkoodattu osaksi HTTP(S)-pyynnön URL-osoitetta.

Kyselyformaatti on seuraavanlainen:

{http-request-method} /{protocol-version}/{serviceId}[/path][?query-parameters]

Kyselyformaatin osien selitykset:

• http-request-method: voi olla standardin mukainen kyselymetodi, esim. GET, POST, PUT, DELETE
• protocol-version: RESTin X-Road-viestiprotokollan versio, jonka täytyy olla r1, kunnes versio päivitetään
• serviceId: alijärjestelmän tunnistus-Id, joka sisältää seuraavat tiedot (SUBSYSTEM on valinnainen): /INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/BARSERVICE
• path: sisältää kutsuttavan palvelun suhteellisen polun
• query-parameters: sisältää palvelulle lähetettävät tiedusteluparametrit.

Seuraavassa on esimerkki REST-kyselystä:

GET /r1/INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/BARSERVICE/v1/bar/zyggy?quu=1

Jos oletetaan, että serviceId osoittaa osoitteeseen https://barservice.example.org/, palveluntarjoaja näkee pyynnön

GET https://barservice.example.org/v1/bar/zyggy?quu=1

Suositellut otsikkotiedot

Vaikka RESTiä käytettäessä on vain yksi pakollinen otsikkotieto (X-Road-Client), myös Content-Type- ja Accept-otsikkotietoja on suositeltavaa käyttää.

Content-Type-otsikkotieto on seuraavanlainen:

Content-Type: application/json; charset=utf-8
Content-Type: multipart/form-data; boundary=something

Vaikka Content-Type-otsikkotietoa ei käytettäisikään, kyselyviesti välitetään silti palvelulle. Tällöin palvelu päättää, mitä viestille tehdään.

Accept-otsikkotieto puolestaan on seuraavanlainen:

Accept: application/xml

Jos Accept-otsikkotietoa ei käytetä, liityntäpalvelin käyttää vakiona arvoa application/json.

Vastaussanoma

Vastauksessa palautetaan liityntäpalvelimen asettamia X-Road-kohtaisia otsikkotietoja. Palvelun ei pidä asettaa näitä, muuten liityntäpalvelin vain ylikirjoittaa ne. Vastauksessa palautettavat otsikkotiedot ovat

• X-Road-Client: määrittää jäsenen/alijärjestelmän, jota käytetään service clientina
• X-Road-Service: määrittää serviceId:n, jota service client kutsuu
• X-Road-Id: uniikki tunniste sanomalle
• X-Road-Request-Hash: vastauksille; sisältää SHA-512-enkoodatun tiivisteen kyselysanomasta
• X-Road-Error: kertoo kyselysanoman käsittelyssä tapahtuneesta virheestä X-Roadissa (hyödyntäjän/tuottajan liityntäpalvelimella)
• X-Road-Request-Id: uniikki tunniste kyselysanomalle.

Seuraavassa on esimerkki REST-vastauksesta:

X-Road-Client: INSTANCE/CLASS/MEMBER/SUBSYSTEM
X-Road-Service: INSTANCE/CLASS/MEMBER/SUBSYSTEM/PETSTORE
X-Road-Id: fa2e18a5-c2cb-4d09-b994-f57727f7c3fb
X-Road-Request-Hash: 4c519cf0-0e5e-4ccf-b72b-8ed6fe289e6e
X-Road-Request-Id: f92591a3-6bf0-49b1-987b-0dd78c034cc3

Virhesanomat

Liityntäpalvelin käyttää HTTP-tilakoodeja virhetilanteen ilmaisemisessa. Käytännössä virheitä on neljää eri tyyppiä:

1. Liityntäpalvelimilla kaikki toimi, mutta palveluntarjoajan järjestelmä palautti virheen.
2. Palveluntarjoajan järjestelmä kohtasi ongelman eikä palauttanut vastausta.
3. Palvelun käyttäjän järjestelmä lähetti kyselysanoman, joka ei noudata RESTin X-Road-viestiprotokollaa.
4. Liityntäpalvelin kohtasi ongelman.

Ylläoleviin virhetyyppeihin liittyvät seuraavat virhekoodit:

1. Järjestelmä tuottaa tilakoodin, vastausyksikön ja HTTP-otsikkotiedot ja palauttaa ne käyttäjälle sellaisinaan.
2. 500: liityntäpalvelin palauttaa tilakoodin, vastausyksikön ja HTTP-otsikkotiedot.
3. 400 – Virheellinen pyyntö: liityntäpalvelin palauttaa tilakoodin, vastausyksikön ja HTTP-otsikkotiedot.
4. 500 – Sisäinen palvelinvirhe: liityntäpalvelin palauttaa tilakoodin, vastausyksikön ja HTTP-otsikkotiedot.

Tilakoodien lisäksi liityntäpalvelin lisää HTTP-otsikkotiedon X-Road-Error, mikäli virhe tapahtuu liityntäpalvelimella. Otsikko sisältää pelkästään virhetyypin. Kaikki tarkempi tieto löytyy muista sanoman tiedoista. X-Road-Error-otsikkotieto voi olla esimerkiksi seuraavanlainen:

Server.ServerProxy.DatabaseError

Tietoturva

Turvallisten REST-palveluiden tulisi tarjota ainoastaan HTTPS-päätepisteitä. HTTPS suojaa siirrossa autentikointitiedot (esim. salasanat, API-avaimet ja JSON Web Tokenit). X-Road ei tue JWT:itä autentikointitapana liityntäpalvelimen ja palvelun välillä. JWT:itä voidaan käyttää lähettämällä ne HTTP-otsikkotiedoissa palvelun käyttäjältä palvelun tuottajalle; X-Road siirtää otsikkotiedot muuttamattomina.

Palveluiden kuvaus

Liityntäpalvelimelle liitettävät REST-palvelut tulee kuvata OpenAPI 3 -määrittelyn mukaisesti.

• OpenAPI 3 -määrittelyAvautuu uuteen ikkunaan.
• Esimerkki liityntäpalvelimelle liitettävien REST-palveluiden kuvauksestaAvautuu uuteen ikkunaan.

Jos lisäät palvelun käyttämällä REST API Base Path -polkua, palvelu ei näy oikein LiityntäkatalogissaAvautuu uuteen ikkunaan., koska siltä puuttuu tekninen rajapintakuvaus. Tämän takia suosittelemme lisäämään REST-palvelut OpenAPI 3 -muotoisina.

Esimerkkipalvelu

Digi- ja väestötietovirasto tarjoaa avoimen datan rajapintapalveluita REST-viestinvälityksen testaamiseen. Avoimen datan palveluiden kuvaukset ja käyttöesimerkitAvautuu uuteen ikkunaan. löydät Liityntäkatalogista.