Retningslinier for WebService i RSD

Retningslinier for WebService i RSD

Når systemer integrerer via web services - uanset om web-servicen kører over HTTP eller MQ - skal følgende retningslinier og politikker for Web Service (WS) efterleves. Kan leverandøren ikke efterleve regionens standarder og politikker for WS skal afvigelserne beskrives. Regionen skelner i den forbindelse imellem intern og eksterne kommunikation, hvor intern kommunikation handler om system til system integration indenfor regionens netværk, hvorimod eksterne system til system integration sker udenfor regionens netværk eksempelvis ved kald til nationale services. 

En Web Services er defineret[i] ved:

 En Web Service er en service, hvor udveklingsformatet er SOAP XML og hvor servicen er beskrevet gennem WSDL

Web services kan eksponeres via forskellige teknologier, der giver servicen nogle forskellige egenskaber. F.eks. vil en HTTP bundet web service kunne kaldes synkront, hvilket er den nemmeste måde at integrere systemer på. Til gengæld vil det kaldende system (klientsystemet) være helt og aldeles afhængig af, at serviceudbyder systemet er operationelt - også selv om servicen blot er en "fire and forget" service.

Intern kommunikation

Webservice der bruges i forhold til intern kommunikation følger en rammeværk kaldet Baseline, som du kan finde mere information om på følgende side http://techwiki.regionsyddanmark.dk/display/public/Baseline.

Endvidere kan du nederst på siden se, hvordan skabelonen for interne webservice skal udformes, se Eksempel intern kommunikation

Transaktioner

Services (uanset type) er ikke-transaktionelle, dvs. de kan ikke indgå i distribuerede transaktioner. Begrundelsen for at implementere distribuerede transaktioner ovenpå SOAP over HTTP forlader sig på en antagelse om at service kald vil blive grupperet i atomare enheder på tværs af systemer.  Det er vigtigt at holde sig for øje, at transaktioner kun har berettigelse for så vidt der er tale om såkaldte CUD operationer (Create, Update, Delete), hvor data modificeres i det modtagende system.

Serviceimplementationer bør i videst muligt omfang benytte underlæggende systemer/komponenters transaktionsmuligheder for at opretholde ACID indenfor serviceimplementationen.







Figur 1 - "Distribuerede transaktioner" kan anvendes inden for systemer

Figuren ovenfor illustrerer med lyseblåt transaktionsgrænsen, som altså er intern i systemet og ikke eksponeres overfor eksterne klienter. Hvert eneste webservice kald og svar indeholder et unikt transaktionsnummer, der bruges til at opnå sporbarhed på tværs af klient og server. Det er et krav at dette nummer er globalt unikt på tværs af tid og sted og i praksis kan et såkaldt Universally Unique Identifier (UUID). Baseline benytter en metadatastruktur som netop tildeler et unikt ID, hvor mere information omkring Baseline metadata kan findes her: Baseline meta data specification

Transaktionsnummeret propageres i en dedikeret SOAP header på alle kald og returneres i en tilsvarende header i alle svar. Et eksempel på et sådant MessageID i en ikke komplet header er vist nedenfor:

<soap:Header>
  <bl:BaselineHeader>
   <bl:BaselineMetaData>
    <bl:ContractId>ContractId</bl:ContractId>
    <bl:LogicalId>LogicalId</bl:LogicalId>
    <bl:TransactionId>TransactionId</bl:TransactionId>
   </bl:BaselineMetaData>
   <bl:properties>
    <bl:name>name</bl:name>
    <bl:value>value</bl:value>
    <bl:type>type</bl:type>
    <bl:qualifier>qualifier</bl:qualifier>
   </bl:properties>
  </bl:BaselineHeader>

</soap:Header>

Værdien af headeren er globalt unik og gælder kun for en enkelt forespørgsel og det tilhørende svar.

Logning

Logning og autorisation er begge eksempler på tekniske aspekter, der passende kan håndteres af integrationsplatformen. For at gøre det muligt at korrelere de centrale logs (i integrationsplatformen) med decentrale logs (i systemerne) skal alle servicekald identificeres ved et unikt ID. Dette ID er som tidligere nævnt indlejret i forhold til baseline metadataspecifikation

På integrationsplatformen skal der logges for revisionsspor, fejllogs og evt. detaljerede logs i forbindelse med fejlsøgning og performancetest.
 
Den unikke meddelelses ID skal logges på integrationsplatformen. Er et system involveret i flere kald skal kalderens MessageID med ned i loggen 

Det anbefales, at mappe alle soap-messageID'er til et system-internt jobId (via en logbesked). Dermed vil det system-interne jobId være med på alle logbeskeder, der produceres internt i systemet. Således kan hele flowet tracet, hvorved det er muligt at fremfinde alle logbeskeder på tværs af systemer, der har med hinanden at gøre. 

Fejlhåndtering

Web Services skal udelukkende eksponere fejl, hvor det er muligt for et klientsystem at foretage sig noget intelligent på baggrund af fejlen, f.eks. bede brugeren om at raffinere input (applikationsaspektet), eller informere brugeren om at vedkommende ikke er autoriseret (tekniske/sikkerhedsmæssigt aspekt).

I webservices mappes fejl til såkaldte SOAP-Faults. Disse repræsenteres i form af fejl-beskeder, som klienter kan reagere meningsfyldt på.  Services skal bygges så de er robuste overfor fejlsituationer i de underliggende komponenter. Det er nødvendigt at servicelaget håndterer både runtime fejl og forretningslogiske undtagelser, så en service-snitflade aldrig bliver utilgængelig pga. problemer med implementationen. WSDL og DGWS definerer wsdl:fault til at dokumentere hvilke undtagelser der kan opstå ved anvendelsen af en service. 

For services defineres fejl gennem SOAP faults i WSDL. Fejl skal defineres så de er passende for abstraktionen, og så det er muligt for klientsystemet at foretage noget intelligent på baggrund af fejlen. 

Versionering

Over tid vil Webservice-snitflader skulle ændres, fordi der er opstået behov for flere informationer, eller fordi procedurer har ændret sig eller nye er kommet til. Under alle omstændigheder vil det være nødvendigt at versionere:

  1. XML Schema  (model ændringer)
  2. WSDL Definitioner (interface ændringer)
  3. WSDL Services (ændringer af endpoints, protokoller)

En robust versioneringsmekanisme må håndtere tilføjelser, sletninger og ændringer af service snitfladen. Samtidig er det nødvendigt, at versioneringsstrategien tager højde for at visse ændringer er mere omfattende end andre. En tilføjelse af en ny metode til et WSDL interface er f.eks. ikke kritisk for eksisterende klienter, der ikke har behov for denne metode. Til gengæld bryder tilføjelsen af en ny parameter til en eksisterende metode interfacet og tvinger alle klienter der bruger den til at blive opdateret. To typer af ændringer til WSDL filer er ukritiske for eksisterende klienter:

  1. Tilføjelse af nye operationer til WSDL Definitioner og
  2. Tilføjelse af nye XML Schema typer, der ikke er indeholdt i andre typer

En lang række af ændringer er ikke bagud kompatible, herunder at fjerne en operation, ændre en operation, ændre strukturen af en datatype etc. Af hensyn til simplicitet defineres i stedet: 

Snitfladebeskrivelser, herunder WSDL og XSD må ikke ændres når de først er publiceret. Kræves en opdatering af snitfladen, laves en ny service / operation.. 

Hvis en ændring ikke er bagud kompatibel, vil klienter skulle ændres for at kunne bruge det nye interface. Man kan vælge at anskue det som om der er kommet et helt nyt interface og beslutte om det gamle skal leve videre parallelt evt. for en tid eller helt fjernes. Hvis en ændring er bagudkompatibel kan klienter blot ændres til at benytte det nye endpoint og/eller de nye targetNamespace værdier uden at skulle kodes yderligere om. 

Nye versioner af både WSDL og XSD filer skal have et nyt targetNamespace efter samme strategi som specificeret i afsnittet om Data Formater, f.eks:

http://rep.oio.dk/<region>.dk/xml/schemas/2005/07/12/SomeModel.xsdfor en ny (major) version af SomeModel.xsd. 

XML rettede retningslinier

Style & Encoding 

Webservices kan operere i to forskellige modus: RPC (Remote Procedure Call) style, hvor interaktionen foregår som et funktionskald med input og output parametre samt Document style, hvor data udveksles vha. dokumenter. 

Diskussion af RPC vs. Document style har 2 forskellige betydninger - en arkitektonisk og en SOAP-specifik. På det arkitektoniske niveau handler det om hvorvidt afsender blot sender data (document style) eller om afsender sender data + angivelse af hvilken operation, modtager skal udføre på data (RPC). På det konkrete SOAP-niveau handler diskussionen om hvordan man skal fortolke SOAP-body'en.

Når der anvendes RPC style følger SOAP XML formatet strukturen for den metode der kaldes. For eksempel angives navnet på metoden i et XML element, ligesom parametre gør det. Når der anvendes Document style kan der udveksles arbitrære XML dokumenter imellem klient og server og der er ikke specielle regler for hvordan data struktureres i henhold til metodens signatur. 

Encoding angiver hvordan data serialiseres mellem afsender og modtager. Hvis der vælges "Encoded" anvendes et prædefineret schema for hvordan data repræsenteres. SOAP definerer f.eks. en SOAP-Encoding, der bla. beskriver hvordan en streng af tekst, primitive typer og arrays angives.

Vælges der "Literal", benyttes et XML Schema som model for interaktionen. Dette Schema definerer den delte model mellem parterne i en webservice interaktion. Kombinationen "style" og "encoding" giver 4 valgmuligheder:

  • RPC-Encoded
  • RPC-Literal
  • Document-Literal
  • Document-Literal-Wrapped (blanding af RPC og document)
  • Document-Encoded

WS-I Basic Profile 1.1 begrænser sættet af tilladelige encodings til Document-Literal og RPC-Literal, mens Den Gode Webservice yderligere begrænser udfaldsrummet til Document-Literal. I regionen fravælges RPC-Literal:

Regionens webservices skal benytte Document-style.

Data Formater Webservices modeller implementeres i regionen vha. XML Schemaer som foreskrevet af Basic Profile 1.1. XML Schemaet beskriver datastrukturer og relationer for den logiske model i et fysisk schema. Schemaet benyttes til strukturering af de data der udveksles mellem parter, der indgår i en webservice interaktion. Schemaet kan selvsagt beskrives på utallige måder og det er her vigtigt at sikre, at de overholder standarder udstukket i regi af IT- og Telestyrelsen (Videnskabsministeriet) for fællesoffentlige løsninger. Disse retningslinjer findes på OIO websitet. Dette indebære, at man skal importere mange skema-filer, da der kun må være en global complextype pr. fysisk fil. En del ws-stakke/xml-parsere har problemer med håndteringen af dette.  I regi af MedCom er der defineret en række schemaer for datatyper med generel anvendelse og typer der er specifikke for det sundhedsfaglige domæne [OIO-MEDCOM].

 
Så vidt muligt benyttes eksisterende OIO XML schemaer herunder MedCom XML schemaer i opbygningen af Regionens webservices
 

Når nye services skal publiceres findes der sjældent et schema allerede og det er da nødvendigt at definere nye, der altså så vidt muligt refererer eksisterende standarder. Disse schemaer har behov for et XML namespace, der unikt identificerer dem som webservices fra regionen:

Regionens XML Schemaer følger W3Cs retningslinjer og har følgende targetNamespace:

http://rep.oio.dk/<region>.dk/xml/schemas/<yyyy>/<mm>/<dd>/<name>.xsd_, hvor <yyyy>/<mm>/<dd> angiver dato for publicering af schemaet, f.eks. 2005/02/19 og <name> er et MixedCase navn på den struktur, schemaet angiver, f.eks. HentMedicinering

Syntaks

Som foreskrevet af Basic Profile, anvendes Web Services Description Language 1.1 (WSDL) til beskrivelse af webservice snitflader, hvilket skal beskrives/dokumenteres. En WSDL fil består overordnet af  Types - En container for data type definitioner baseret på et typesystem (f.eks. XML Schema)

  • Message - En abstrakt, typificeret definition af det data, der kommunikeres.
  • Operation - En abstrakt beskrivelse af en handling, understøttet af en service.
  • Port Type - Et abstrakt sæt af operationer understøttet af et eller flere endpoints. Port typer er semantisk ækvivalente til abstrakte datatyper eller "interfaces" i Java/.NET. I WSDL 2.0 er PortType da også omdøbt til Interface.
  • Binding - En konkret protokol og data format specifikation for en given port type.
  • Port - Et enkelt endpoint defineret som kombinationen af en binding og en netværksadresse. I WSDL 2.0 er Port omdøbt til Endpoint for at afspejle dette.
  • Service - En samling relaterede endpoints (ports).

WSDL filer kan være kompakte og indeholde alle ovennævnte strukturer eller de kan være tynde og bestå af flere fysiske filer, der refererer til hinanden, som vist på figuren nedenfor.

Figur 2 - import i WSDL 

Fordelen ved en kompakt WSDL beskrivelse er at én fil beskriver hele snitfladen, som derved er selvindeholdt og værktøjsvenlig. Ulempen er, at filen ofte bliver stor og i det omfang der findes mere end én binding (f.eks. FTP, SMTP) er genbrug af port typerne ikke muligt.

I regionale services består en WSDL beskrivelse som udgangspunkt af en fil der indeholder:

  1. Modeller i form af XML schemaer (.XSD)
  2. WSDL definitioner
  3. WSDL services

Bliver filen for voldsom at lave selvindeholdt, f.eks. pga. transitive referencer, tillades import af schemaer.Det er tilladt at definere flere 'bindings' for en service, så den kan eksponeres via flere protokoller (f.eks. HTTP og MQ).

Semantik og dokumentation

Hvor WSDL filer definerer syntaksen for en service, mangler der en pendant til at beskrive semantikken. Det er et krav, at følgende beskrives i forbindelse med WSDL:

  • Funktionalitet: Hvad sker der når man kalder en service? Dette er koblingen til den use-case, servicen udfører.
  • Betingelser: Prconditions (Hvad skal være opfyldt, før denne service kan kaldes?) Services, der leverer følsomme data, kræver f.eks. autentifikation.
  • Domæne: Hvad er betydningen af parametrene / servicen i forhold til en faglig forståelse? I sundhedsdomænet kunne det være referencer til HL/7, GEPJ, SKS, ATC etc.
  • Effekter: Hvilke side-effekter er der ved at kalde en service? En service kunne gennemføre en betaling, logge data i en audit log etc.

Denne type information kan ikke beskrives struktureret vha. standard WSDL og kan derfor højst indgå i ustrukturerede tekst-felter.  Service udformning beskrives i WSDL, hvor består af en række elementer der enten er konkrete eller abstrakte.

Ekstern kommunikation

Ved ekstern kommunikation læner regionen sig om af den *"Den Gode Web Service".*I sommeren 2006 udkom MedComs Den Gode Webservice (DGWS) i version 1.0. Specifikationen er en profil for webservicebaseret interaktion i sundhedsvæsenet, der baserer sig på nationale og internationale standarder, herunder WS-I, OIO, WS-Security, mm. DGWS indsnævrer spillerummet for hvordan akkreditiver til brug ved autentifikation transporteres til 5 niveauer: ingen akkreditiver, brugernavn / password, digital signatur med VOCES, digital signatur med MOCES og digital signatur på hele kuverten med MOCES. Profilen definerer yderligere et sæt fælles data der altid medsendes i SOAP headere, herunder oplysninger om afsendersystemet, metaoplysninger om beskeden, samt oplysninger om brugeren hvis der er en sådan. Ud over et fælles kuvertformat defineres samtidig en række brugsscenarier og arketyper for kommunikation, samt præciseringer af hvordan service snitflader beskrives med WSDL.

 Ved ekstern kommunikation - som er karakteriseet ved system til system kommunikation udenfor regionens netværk eksempelvis ved tilgåelse af nationale services - skal webservicen overholde profilen som er fastlagt i MedCom's "Den Gode Web Service" 


Den seneste version af den Gode Web Service kan hentes på http://www.medcom.dk/wm110202

Eksempel intern kommunikation

Skabelonen benytter sig af følgende Baseline metadata som kan downloades her: BaselineMetadata.zip

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
    soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

    <soap:Header>
        <bl:BaselineHeader xmlns:bl="http://ip.rsd.dk/bo"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://ip.rsd.dk/bo datatypes/baseline/BaselineHeader.xsd ">
            <bl:BaselineMetaData>
                <bl:ContractId>ContractId</bl:ContractId>
                <bl:LogicalId>LogicalId</bl:LogicalId>
                <bl:TransactionId>TransactionId</bl:TransactionId>
            </bl:BaselineMetaData>
            <bl:properties>
                <bl:name>name</bl:name>
                <bl:value>value</bl:value>
                <bl:type>type</bl:type>
                <bl:qualifier>qualifier</bl:qualifier>
            </bl:properties>
        </bl:BaselineHeader>
    </soap:Header>

    <soap:Body>
        ... ...
        <soap:Fault>... ...</soap:Fault>
    </soap:Body>

</soap:Envelope>


[i] http://en.wikipedia.org/wiki/Web_service

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.