Den gode webservice

Følgende beskriver retningslinjer for webservices udstillet af STAR. Services udstilles primært af DFDG, men kan også udstilles af de enkelte applikationer, hvis de ikke arbejder med entiteter som er omfattet af DFDG.

Strategi for modellering af webservices

Inden en service udvikles og modelleres bør følgende strategier iagttages:

1. Opdel webservicesniflader så de er målrettet forretningsoperationer inden for et forretningsdomæne
   
   • En webservice bør kun opfylde et veldefineret forretningsbehov (Separation of concerns), målret services mod aftagernes forretningsbehov (interface segregation). En service der gør mange ting ender med at blive for kompleks (svær at forstå) og bliver mere hyppigt ramt af forretningsændringer.
   • Udstil smallere mere målrettede services frem for brede generiske
   • Sæt dig ind i hvad forretningsgangen er i kommuner og a-kasser, hvordan skal servicen udvikles så den understøtter en effektiv og fleksibel arbejdsgang. Erfaringen er at services der ikke udvikles med dette sigte direkte fejler eller fordyrer implementeringen unødigt.
2. Undlad at udstille domæneobjekter direkte i snitfladen, hvis de medfører at der udveksles elementer/attrubutter som ikke er en del af operationen
   • Medtag kun de felter som reelt er input til serviceoperationen, services bliver på denne måde mere selvforklarende
   • Tilbyd hellere dedikerede services end services der kan tilfredsstille flere forretningsbehov
   • En tommelfingerregel er at hvis over 1/4 af felterne ikke bruges i en forretningssammenhæng, så bør der overvejes en dedikeret service.
3. Udstil ny og gammel webserviceversion parallelt
   • Hvis muligt bør gammel version bibeholdes i en release parallelt med den nye inden den udfases
4. Anvend ensartet navngivning og typedefinitioner
   • Anvend samme navngivning og typer på tværs af services
   • Sørg for at typer og syntaks-validering så vidt mulig fremgår af WSDL-kontrakten (XML skemaet).
5. Tilbyd webserviceoperationer, der tilgodeser forskellige klienttyper
   • Tilbyd både skriveoperationer, læseoperationer og operationer der kan gå på tværs af data, f.eks. at returnere en liste eller foretage en søgning, hvis der er et forretningsbehov for dette
6. Underret aftagere når data ændres og ved forretningshændelser
   • Udsend WSRM hændelser når data oprettes, ændres eller slettes.

Strategi for ændring af webservices

Følgende skal forsøges imødekommet ved konstruktion / vedligehold af webservices / snitflader mod andre systemer:

• Forretningsændringer kan foretages i DFDG uden at snitfladerne samtidig skal ændres
• Ændringer til snitfladerne foretages sådan at aftagernes applikationer i en periode kan fungere uændret, altså uden at skulle opdateres samtidig
• Ændringer der kræver samtidig opdatering af aftager-applikationerne, afgrænses så de rammer så få applikationer som muligt
• Ændringer der kræver samtidig ændring af alle aftagerapplikationer skal så vidt muligt undgås.
  • Lovgivning og andre hensyn kan kræve en samtidig ændring

Versionsstyring af webservicesnitflade

I alle tilfælde hvor eksisterende webservice - WSDL og/eller tilhørende skemafiler med entiteter - ændres, er der tale om en ny version af webservicen. Alle gældende operationer kopieres til ny version, så aftager der ønsker at anvende servicen ikke skal tvinges til at anvende flere samtidige versioner.

Webservice-operationer kan dog tilføjes den eksisterende webservice-version, hvis der ikke foretages ændringer til eksisterende operationer og entiteter. Generelt kan 'non-breaking' ændringer foretages. Fjernelse (udfasning) af webservice-operation kan foretages uden versionsændring, men skal selvfølgelig varsling.

 Alle webservices versioneres via to mekanismer:

1. Namespace-versionering
2. URL-versionering

Så vidt det overhovedet er muligt skal DFDG udstille nuværende og forrige version af hver webservice i en periode efter at servicen har fået nyt versionsnummer. Dette skal sikre en højere grad af uafhængighed mellem service udbyder og aftager. Dette velvidende er der er situationer hvor det ikke er muligt at udstille to services parallelt.

 Tidligere version udfases ved næste release, så der typisk arbejdes med et udfasningsvindue på 3 mdr.

 Kodelister der anvendes af en service kan ændres uden at servicen skifter version.

Typer kan deles (shared types) mellem forskellige webservices. Kun entiteter som forventes at være langtidsholdbare (a la OIO typer) deles. Shared types i STAR deles som udgangspunkt af DFDG.

Namespace-versionering

Hver version af en entitet (datatype) der udstilles via en webservice versioneres via et entydigt ”namespace” . Samme version af en entitet har samme navn og namespace på tværs af services.

• http://service.bm.dk/<Servicekatalog>/<ÅÅÅÅ>/<MM>/<DD>/<typenavn>/

• F.eks.: http://service.bm.dk/pjaktass/2013/12/19/JoblogEntry/

Hvis en webservice, en webservice-operation eller en af de entititer den indeholder skifter version får den et nyt namespace. De entiteter der anvendes i den som er uændrede skal have uændret version (namespace).

URL-versionering

Hver ny version af en webservices, placeres på en entydig URL, hvori der indgår et versionsnummer, versionsnummer tælles fortløbende ud fra formen:

• https://server/webservicebibliotek/versionsnummer/servicenavn/

Sikkerhed og logning

Services der udstilles af DFDG og andre af STAR's systemer skal følge samme sikkerhedsmodel som DFDG services.

Alle webservices udstilles via SOAP-XML grænseflade og via HTTPS forbindelse, som kræver at klienten anvender et funktionscertifikat. Udover certifikatet angiver aftager i SOAP header hvilken organisation aftageren kalder på vegne af.

Derudover skal alle webservices uanset om de foretager læse- eller skrive-operationer forsynes med unik identifikation af hvem (eller hvad) der foretager kaldet, så dette kan logges.

Undtaget fra disse er offentlige webservices, der kan udstilles uden sikkerhed.

Alle service metoder skal dekoreres med en til flere AllowAccessAttribute, hvori det angives, hvilken organisationstype, der har ret til at kalde den konkrete metode samt hvilke borgere, som organisationstypen kan tilgå, eksempelvis alle borgere eller egne borgere. Se nærmere om sikkerhedsmodel i DFDG på DFDGs Sikkerhedsmodel (FOCES) (sikkerhedsmodel fra og med 2015) og på Sikkerhed som beskriver OCES sikkerhedsmodellen som er under udfasning

Principper for validering af input

Mængden af valideringer på inputdata er en afvejning af omkostninger og kvalitet. STARs principper er her, at inputdata valideres ud fra følgende kriterier:

• Valideringen sikrer kritisk datakvalitet, som er defineret ved at borgers rettigheder eller ydelsesgrundlag kan blive fejlagtigt hvis der ikke valideres
• Valideringen sikrer sammenhænge i data som er vigtige for at DFDG fungerer (fx mellem fravær og kontaktgrupper) 
• Valideringen sikrer at sammenhænge og data er tilstede, som udgør målepunkter i styrelsens brug af data eller i tilsynet med a-kasser eller jobcentre

Fejlhåndtering

Alle webservices skal ved fejl håndteret af applikationen kaste følgende SoapFault:

FaultDetails

Udarbejdelse af WSDL filer

Services udarbejdes med udgangspunkt i kontrakten (WSDL filen), dette for at sikre at kontrakten bliver pæn og anvender de ønskede OIO og egne shared typer.

For ikke at skulle skrive WSDL filer i hånden skriver vi dem som annotering i de interfacefiler der skrives.

Navngivning af services

Services gives et sigende navn der dækker den forretningsfunktionalitet der stilles til rådighed:

• <ServiceOmråde>Service

Navngivning af metoder

Metoder vil typisk have følgende navne:

CRUD-mønster

Forretningsmønster

Navngivning af elementer

Navne og typer af elementer følger så vidt muligt godkendte og anbefalede OIO typer. OIO har defineret navngivnings- og designregler gennem NDR 3.2, som er hele grundlaget for etablering af OIOXML og dets OIO-datadefinitioner. Typiske elementnavne eller elementnavnendelser er ('...' skal være et veldefineret forklarende navn):

I det nuværede system anvende i mange tilfælde ...Date hvor der menes ...DateTime. Det bør rettes ved fremtidige ændringer til services. 

Bemærk: Om det skal være Date eller DateTime skal overvejes nøje, det er set at et DateTime felt anvendes som et Date felt.

Obligatoriske elementer

Der er få obligatoriske felter som skal medtages i hver webservicekald. De felter der skal være med i alle kald er angivet beskrevet i afsnittet ”Obligatoriske metadata i kaldet” nedenfor. Udover disse er der en række felter som nok bør findes i kaldet.

Inputparametre:

• Identifier – Hvor der arbejdes med en entitet bør der altid medsendes en entydig identifikation af entiteten, dette bør være i form af en GUID. Dette gælder ved læse og opdateringsoperationer.

Outputparametre:

Normalt returneres ID på entiteten der arbejdes med, under oprettelse returneres ID på den oprettede entitet:

• ...Identifier - Ved oprettelse skal ID på den oprettede entitet som minimum returneres, også selvom kaldet har angivet denne.

Nedarvning i servicerequest

Der er indført en BaseRequest i foundation, som request-klasserne kan arve fra. Denne base-klasse indeholder ActiveOrganisationHeader og RequestUserMetadataHeader,så disse kun implementeres 1 gang. Dette minimerer kodeduplikation ud over alle services, for både Jobnet, Vitas og DFDG. 

Obligatoriske metadata i kaldet

De obligatoriske metadata i kaldet kan findes under STARs sikkerhedsmodel