Gå direkt till innehållet.
Suomi.fi-informationsled

X-Road-dataöverföringsprotokoll

I den här artikeln beskrivs X-Road-dataöverföringsprotokollet för Suomi.fi-informationsleden.

Anslutningen till Informationsleden förutsätter att det system som ska anslutas kan skicka och ta emot SOAP- och REST-meddelanden i den form som X-Road förutsätter. I praktiken innebär detta att SOAP- och REST-meddelandena ska innehålla vissa rubrikuppgifter som definierats i X-Road-protokollet. Dessutom ska enkät- och svarsparametrarna inkluderas i SOAP-meddelandets body-del på det sätt som fastställts i X-Road-protokollet. Version 7 av X-Road använder SOAP versionen 1.1.

I artikeln presenteras:

  1. X-Road-kommunikationsprotokoll för SOAP. Bekanta dig närmare med X-Roads protokollbeskrivning för SOAP (på engelska)Öppnas i ett nytt fönster.
  2. X-Road-kommunikationsprotokoll för REST. Bekanta dig närmare med X-Roads protokollsbeskrivning för REST (på engelska)Öppnas i ett nytt fönster.

1. X-Road-kommunikationsprotokoll för SOAP

HTTP-rubrikuppgifter

X-Road förutsätter att HTTP-rubrikinformation i tabell 1 används för meddelanden som skickas via den. I meddelanden som innehåller bilagor ska uppgifterna i rubriken Content-Type vara multipart/related, annars ska värdet text/xml användas. Fältet SOAPAction kan lämnas tomt eller definieras som ett uttryck för önskad URI-definition.

HTTP-rubrik

Värde

Content-Type

text/xml eller multipart/related

SOAPAction

valid URI eller tom *)

*) Anslutningsservern förvarar och förmedlar SOAPAction-rubrikposten till tjänsten från och med version 6.16.0 av X-Road. Valid URI innebär att URI är inbyggt i inkastmärkena (anslutningsserverprogrammet kontrollerar detta).

Exempel på rätt definierad SOAPAction-rubrik:

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

Exempel på ett korrekt angivet tomt värde i SOAPAction-rubriken:

SOAPAction: ""

Gränssnittsbeskrivningar

X-Road förutsätter att de tjänster som ansluts beskrivs på WSDL-språk. XML-scheman som beskriver strukturen på förfrågnings- och svarsmeddelanden kan antingen inkluderas direkt i WSDL-beskrivningen eller beskrivas i separata XML Schema Definition (XSD) -filer. I WSDL-beskrivningen hänvisas till dessa XSD-filer med hjälp av transaktionsdefinitionen.

När XSD-filer används bör man beakta att xml:include inte fungerar eftersom användaren inte har tillgång till WSDL-leverantörens datasystem. Däremot xml:import fungerar, men XSD-filen måste erbjudas till det offentliga internet och i transaktionen måste man ange en absolut adress och inte bara en relativ adress.

Detta är till exempel rätt sätt:

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

Det här är fel sätt:

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

I scheman ska namnrymder och entydiga namn användas för elementen. De datatyper som används i WSDL-beskrivningen måste finnas på de nätverksplatser som namnrymderna definierar; annars misslyckas WSDL:s etablering på anslutningsservern. Detta bör beaktas i synnerhet i det fall att de namnrymder som används inte är allmänt tillgängliga på internet, utan de har gjorts till exempel endast för ett visst, slutet ändamål. Då måste namnrymden erbjudas till det offentliga internet så att det är möjligt att använda den.

I scheman rekommenderas det att använda elementFormDefault=”qualified”-specifikationenÖppnas i ett nytt fönster.. Enligt den ska alla element som används i meddelanden som grundar sig på det aktuella XML-schemat uppfylla kraven i de namnrymder som fastställts i schemat. I praktiken får meddelandena alltså inte innehålla element som inte har definierats i schemat eller i de namnrymder som schemat använder. På detta sätt förebyggs uppkomsten av namnkonflikter och säkerställs att varje element kan identifieras entydigt.

I WSDL-dokumentet ska document/literal-bindning (binding style = ”document”; use = ”literal”) användas. Binding style ska vara ‘document’. Värdet på flera attribut måste vara ‘literal’.

Informationsledens WSDL-exempel utan request-response-omslag (XML, 7,31 kB)Öppnas i ett nytt fönster.


Informationsledens WSDL-exempel med request-response-omslag (XML, 8,86 kB)Öppnas i ett nytt fönster.


Nedan följer ett exempel på en WSDL-fil som presenterar tjänsten getRandom:

<?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>


I början av WSDL presenteras de nödvändiga namespacet. OBS! Använd alltid den absoluta adressen.

<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">


Datatyper för erbjudna operationer:

<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-parametrar för begäran i rubriken:

<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>


Innehållet i den tjänsten som erbjuds. Strukturen ska alltid vara följande:

<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>


Operation som erbjuds:

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


Presentation av operation som erbjuds. Input body innehåller en enkät till själva operationen och headerna styr enkäten till rätt service. Output body är operationens svar och vidare den service som enkäten hade kommit till.

<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>


Hela namnet av den servicen som erbjuder de ovannämnda operationerna:

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


SOAP-rubrikuppgifter

De SOAP-rubrikuppgifter som X-Road förutsätter presenteras i tabell 2.

Fält

Obligatorisk

Tilläggsuppgifter

service

x

Se tabell 3.

client

x

Se tabell 3.

userId


Anropande slutanvändares användarnamn inklusive generering i kundsystemet. Om anropet automatiskt genereras av kundsystemet kan även namnet på kundsystemet användas.

Obs! Personbeteckningen ska inte skickas i detta fält, eftersom innehållet i fältet sparas som okrypterat i anslutningsserverns meddelandelogg.

id

x

Unik identifikation som identifierar anrops- och svarsmeddelandet. Den som skickar inbjudan ansvarar för att generera koden.

issue


I fältet kan förmedlas annan fritt formulerad information gällande inbjudan.

requestHash


Endast i SOAP response-meddelanden. Producentens (producer) anslutningsserver läggs till.

requestHash@algorithmld


Endast i SOAP response-meddelanden. Producentens (producer) anslutningsserver läggs till.

protocolVersion

x

X-Road-dataöverföringsprotokollets versionsnummer som används i meddelandet. I versionen av X-Road >= 6.4 är versionsnumret för dataöverföringsprotokollet 4.0.

Tabell 2. SOAP-rubrikuppgifter.

Svarsmeddelandet ska innehålla exakt samma rubrik som förfrågningsmeddelandet.

För att meddela den som utnyttjar tjänsten (consumer) används ett client-element och för att meddela producenten (producer) ett serviceelement. Båda elementen består av flera underelement, vars innehåll identifieras av den som meddelar och av producenten.

  • organisationsspecifika koder: sdsbInstance, memberClass, memberCode
  • systemspecifika koder: xRoadInstance, memberClass, memberCode, subsystemCode
  • tjänstespecifika koder: xRoadInstance, memberClass, memberCode, subsystemCode, getRandom, serviceVersion.

I exemplet nedan är utnyttjarens kod FI.GOV.12345-6.ConsumerService och producentens kod FI.GOV.65432-1.DemoService.getRandom.v1.

Rubrik i version 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>

I tabell 3 presenteras korta beskrivningar av innehållet i underelementen i client- och serviceelementen.

Element

Beskrivning

xRoadInstance

Identifierare som identifierar X-Road-instansen. Identifikationen består av en landskod enligt ISO-standarden och en bilaga som identifierar den tekniska miljön (utvecklingsmiljön, provmiljön, produktionsmiljön).

memberClass

Unik identifikation som uttrycker organisationens typ inom en enskild instans, till exempel statsförvaltningens organisation (GOV), kommunen (MUN), ett privat företag (COM) eller en stiftelse (ORG).

memberCode

En beteckning som identifierar en enskild organisation och som ska vara unik åtminstone inom den valda organisationstypen. FO-nummer.

subsystemCode

Identifierare för ett enskilt informationssystem eller en logisk tjänste-/systemhelhet som ansluts till Informationsleden.

serviceCode

Namn/kod för enskild SOAP-tjänst som publicerats i Informationsleden.

serviceVersion

SOAP-tjänstens version, till exempel v1 eller v2.

Tabell 3. Client- och serviceelement.

Tilläggsuppgifter om X-Roads koder.

SOAP Body

De enkät- och svarsparametrar som används i informationssystemet som ansluts till Informationsleden ska inkluderas i SOAP-meddelandets bodydel på det sätt som fastställts i X-Road-protokollet. Från och med version 6 av X-Road är det dock inte längre obligatoriskt att använda request/response-omslag.

Organisationer som ansluter sig till Informationsleden får själva besluta om användningen av request/response-omslag i sina egna tjänsters kopplingar till Informationsleden. Användningen av omslag ska dock vara enhetlig för en enskild tjänst. Omslag ska alltså användas både i förfrågnings- och svarsmeddelanden eller ingendera.

Förfrågningsmeddelande

Förfrågningsmeddelanden (request) som skickas via X-Road ska vara följande när request-/response-omslag inte används:

Informationsledens förfrågningsmeddelande, exempel utan request-response-omslag (XML, 1,22 kB)Öppnas i ett nytt fönster.

<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>


När man använder request-/response-omslag ska frågemeddelandet vara följande:

Informationsledens förfrågningsmeddelande, exempel vid användning av request-response-omslag (XML, 1,31 kB)Öppnas i ett nytt fönster.

<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>


Enkätmeddelandets nyttobelastning

Enkätmeddelandets nyttobelastning (payload) ska placeras i SOAP-meddelandets body-del. XML-elementet med nyttobelastning ska namnges enligt tjänst. Tjänstens namn definieras i SOAP-meddelandets rubrik i serviceCode-elementet under serviceelementet.

I följande exempel presenteras en inbjudan till tjänsten helloService utan request. För tydlighetens skull har alla överflödiga element utelämnats.

<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>


Se även oförenklade förfrågningsmeddelanden:

oförenklad inbjudan till helloService-tjänsten utan request


enkel inbjudan till helloService-tjänsten vid användning av request

Svarsmeddelande

Svarsmeddelanden som skickas via X-Road ska alltid innehålla samma rubrikuppgifter som förfrågningsmeddelandet.

Svarsmeddelanden (response) som skickas via X-Road ska ha följande form när request-/response-omslag inte används:

<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>


Vid användning av request-/response-omslag ska svarsmeddelandet vara följande:

<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>


Se även oförenklade svarsmeddelanden:

oförenklat svarsmeddelande utan request-response-omslag (XML, 1,28 kB)Öppnas i ett nytt fönster.

oförenklat svarsmeddelande vid användning av request-response-omslag (XML, 1,43 kB)Öppnas i ett nytt fönster.


Nyttobelastning för svarsmeddelandet

Nyttobelastningen (payload) i svarsmeddelandet ska placeras i bodydelen i SOAP-meddelandet. XML-element som innehåller nyttobelastning ska namnges så att elementets namn består av tjänstens namn och en Response-bilaga som läggs till efter namnet. Tjänstens namn definieras i SOAP-meddelandets rubrik i serviceCode-elementet under serviceelementet.

Nedan visas svarsmeddelanden som har returnerats av tjänsten helloService. För tydlighetens skull har alla överflödiga element utelämnats.

Exempel utan request/response-omslag:

<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>

Exempel på request/response-omslag:

<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>

Se även oförenklade svarsmeddelanden:

oförenklat svarsmeddelande i helloService-tjänsten utan request-response-omslag


oförenklat svarsmeddelande i helloService-tjänsten med request-response-omslag


Felmeddelanden

X-Road gör det möjligt att återställa två typer av felmeddelanden: standard SOAP error och non-technical SOAP error.

Standard SOAP error

Det är inte obligatoriskt att inkludera SOAP-rubrik i felmeddelandet standard SOAP error men det rekommenderas. Felkoder enligt SOAP-definitionerna ska användas som felkoder (fault code)Öppnas i ett nytt fönster.:

VersionMismatch

  • Felaktig namnrymd har använts i SOAP-meddelandet. Därför genererar SOAP-handläggaren felkoden om versionerna inte är kompatibla. Se närmare hur namnrymden ska vara definierad.

MustUnderstand

  • Barnelementet i SOAP-rubrikelementet innehåller attributet MustUnderstand med värdet TRUE eller 1, men mottagarens SOAP-handläggare kan inte identifiera eller hantera elementet.

Client

  • Med Client-felkoden hänvisas du till det felaktiga innehållet i kallelsemeddelandet. Då är kundändens kallelsemeddelandet felaktig.

Server

  • Med Server-felkod avses andra felsituationer än de som orsakas av innehållet i kallelsemeddelandet. Då har det skett ett fel i hanteringen av inbjudan på tjänstens sida.
<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 är ett programspecifikt felmeddelande. Den ska innehålla en applikationsspecifik felkod (fault code) och en felbeskrivning (fault string). Meddelandet ska innehålla SOAP-rubrikuppgifter.

<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>

I felmeddelandet non-technical SOAP error kan man använda request- /response-omslag på samma sätt som i vanliga svarsmeddelanden. Om paketen används i förfrågnings- och svarsmeddelanden ska de också användas i ett non-technical SOAP error -felmeddelande.

<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>


Exempeltjänst

Exempel utan request/response-omslag

Som exempel används den enkla tjänsten helloService. Som parameter för förfrågningsmeddelandet anges användarens namn och i svarsmeddelandet returneras en hälsning till användaren i fråga. Se exempel på tjänsten:

Informationsledens exempeltjänst, gränssnittsbeskrivning utan omslag (XML, 7,31 kB)Öppnas i ett nytt fönster.

Informationsledens exempeltjänst, inbjudan utan omslag (XML, 1,22 kB)Öppnas i ett nytt fönster.

Informationsledens exempeltjänst, svarsmeddelande utan omslag (XML, 1,28 kB)Öppnas i ett nytt fönster.


Exempel på request/response-omslag

Som exempel används den enkla tjänsten helloService. Som parameter för förfrågningsmeddelandet anges användarens namn och i svarsmeddelandet returneras en hälsning till användaren i fråga. Se exempel på tjänsten:

Informationsledens exempeltjänst, gränssnittsbeskrivning med omslag (XML, 8,86 kB)Öppnas i ett nytt fönster.

Informationsledens exempeltjänst, inbjudan med omslag (XML, 1,31 kB)Öppnas i ett nytt fönster.

Informationsledens exempeltjänst, svarsmeddelande med omslag. (XML, 1,43 kB)Öppnas i ett nytt fönster.


2. X-Road-kommunikationsprotokoll för REST

REST fungerar parallellt med SOAP-meddelanden. Bekanta dig med detaljerna i RESTs X-Road-kommunikationsprotokoll (på engelska)Öppnas i ett nytt fönster., såsom valfria rubrikuppgifter.

HTTP-rubrikuppgifter

Vid användning av REST har anroparen endast en obligatorisk rubrik, X-Road-Client. Övriga rubrikuppgifter är valfria. X-Road-Client definierar organisationen/subsystemet som anropar tjänsten. Koden för subsystemet är valfri.

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

X-Road-anslutningsservern överskriver alltid följande rubrikinformation:

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

Förfrågningsmeddelande

X-Road använder HTTP version 1.1. Organisationen/subsystemet definieras med hjälp av HTTP-rubrik. Systemet som anropas är enkodat som en del av URL-adressen till HTTP(S) -begäran.

Förfrågningsformatet är följande:

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

Förklaringar till enkätformatets delar:

  • http-request-method: kan vara en standardenlig enkätmetod, tex GET, POST, PUT, DELETE
  • protocol-version: REST X-Road-meddelandeprotokoll som ska vara r1 tills versionen uppdateras
  • serviceId: identifierings-Id för subsystemet som innehåller följande uppgifter (SUBSYSTEM är valfritt): /INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/BARSERVICE
  • path: innehåller en relativ väg för tjänsten som ska kallas
  • query-parameters: innehåller underrättelseparametrar som skickas till tjänsten.

Nedan följer ett exempel på REST-enkäten:

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

Om man antar att serviceld är adresserat till htpps://barservice.example.org/, ser tjänsteleverantören begäran

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

Rekommenderade rubrikuppgifter

Även om det endast finns en obligatorisk rubrikinformation (X-Road-Client) vid användning av REST, rekommenderas det att även uppgifterna i rubrikerna Content-Type och Accept används.

Uppgifterna i rubriken Content-Type är följande:

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

Även om informationen i rubriken Content-Type inte används, förmedlas frågemeddelandet ändå till tjänsten. Då bestämmer tjänsten vad som ska göras med meddelandet.

Uppgifterna i rubriken Accept är följande:

Accept: application/xml

Om informationen i rubriken Accept inte används, använder anslutningsservern värdet application/json som standard.

Svarsmeddelande

I svaret returneras de X-Road-specifika rubrikuppgifterna som anslutningsservern har ställt in. Tjänsten ska inte ställa in dessa, annars överskriver anslutningsservern dem. De rubrikuppgifter som ska returneras i svaret är:

  • X-Road-Client: definierar medlem/subsystem som används som service client
  • X-Road-Service: definierar serviceld som service client anropar
  • X-Road-Id: unik kod för meddelandet
  • X-Road-Request-Hash: för svaren; innehåller en SHA-512-enkodad sammanfattning av enkätmeddelandet
  • X-Road-Error: berättar om fel i hanteringen av förfrågningsmeddelandet i X-Road (på utnyttjarens/producentens anslutningsserver)
  • X-Road-Request-Id: unik identifikation för förfrågningsmeddelandet.

Nedan följer ett exempel på REST-svaret:

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

Felmeddelanden

Anslutningsservern använder HTTP-statuskoder för att uttrycka en felsituation. I praktiken finns det fyra olika typer av fel:

  1. Allt fungerar på anslutningsservrarna men tjänsteleverantörens system återställde felet.
  2. Tjänsteleverantörens system stötte på ett problem och returnerade inte svaret.
  3. Serviceanvändarens system skickade ett förfrågningsmeddelande som inte följer RESTs X-Road-kommunikationsprotokoll.
  4. Anslutningsservern stötte på ett problem.

Följande felkoder gäller för ovanstående feltyper:

  1. Systemet skapar statuskoden, svarsenheten och HTTP-rubrikerna och returnerar dem som sådana till användaren.
  2. 500: anslutningsservern returnerar statuskod, svarsenhet och HTTP-rubrik.
  3. 400 - Fel begäran: anslutningsservern returnerar statuskoden, svarsenheten och HTTP-rubrikuppgifterna.
  4. 500 - Internt serverfel: anslutningsservern returnerar statuskoden, svarsenheten och HTTP-rubrikuppgifterna.

Förutom statuskoderna lägger anslutningsservern till HTTP-rubrikinformationen X-Road-Error, om felet sker på anslutningsservern. Rubriken innehåller endast feltypen. All närmare information finns i meddelandets övriga uppgifter. X-Road-Error-rubriken kan till exempel se ut så här:

Server.ServerProxy.DatabaseError

Datasäkerhet

Säkra REST-tjänster ska endast erbjuda HTTPS-terminaler. Vid överföringen skyddar du autentiseringsuppgifterna (t.ex. lösenord, API-nycklar och JSON Web Token). X-Road stöder inte JWT som autentiseringssätt mellan anslutningsservern och tjänsten. JWT kan användas genom att skicka dem i HTTP-rubrikuppgifterna från utnyttjaren till tjänsteproducenten; X-Road överför rubrikuppgifterna oförändrade.

Beskrivning av tjänsterna

De REST-tjänster som ansluts till anslutningsservern ska beskrivas enligt definitionen OpenAPI 3.

Om du lägger till en tjänst med REST API Base Path, visas tjänsten inte på ett korrekt sätt i API-katalogenÖppnas i ett nytt fönster. eftersom den saknar en teknisk gränssnittbeskrivning. Därför vi rekommenderar att lägga till REST-tjänster enligt OpenAPI 3 beskrivning.

Exempeltjänst

Myndigheten för digitalisering och befolkningsdata tillhandahåller gränssnittstjänster för öppna data för testning av REST-meddelanden. Beskrivningar av tjänsterna för öppna data och användningsexempletÖppnas i ett nytt fönster. finns i API-katalogen.

Uppdaterad: 30.10.2024

Är du nöjd med innehållet på denna sida?