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.
Tilføj retningslinjer omkring store dokumenter. Vi ønsker ikke at store dokumenter sendes ind vi de almindelige webservices, men at disse sendes særskilt og refereres via GUID. |
Inden en service udvikles og modelleres bør følgende strategier iagttages:
Følgende skal forsøges imødekommet ved konstruktion / vedligehold af webservices / snitflader mod andre systemer:
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:
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.
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).
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:
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
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:
Alle webservices skal ved fejl håndteret af applikationen kaste følgende SoapFault:
Feltnavn | Type | Forekomst | Beskrivelse |
---|---|---|---|
ErrorCode | int | 0-1 | Fejlkode, denne kommer fra kodelisten GetErrorCodeList |
Message | string | 0-1 | Teksten fra kodelisten |
InnerException | string | 0-1 | Hvis fejlen er forårsaget af en indre fejl kastes en |
StackTrace | string | 0-1 | Stacktrace fra koden der forårsagede fejlen |
Source | string | 0-1 | Kilde til fejlen, Client eller Server |
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.
Services gives et sigende navn der dækker den forretningsfunktionalitet der stilles til rådighed:
Metoder vil typisk have følgende navne:
Metodenavn | Beskrivelse |
---|---|
Create.... | Opret eller aflever data |
Update... | Opdater tidligere oprettet data |
Delete... | Slet (eller slettemarker) tidligere oprettet data |
Get... | Hent tidligere oprettet data, enten som enkelt opslag eller en liste |
Get... Info/Status | Get....Info bruges som metodenavn når der udleveres "full-collections" hvorimod Get...Status anvendes til status-collections som giver et dashboardlignende eller overbliks-udsnit af data. |
Metodenavn | Beskrivelse |
---|---|
Forretningsprocesnavn | Anvend et sigende navn der klart fortæller hvad det er operationen gør |
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):
Feltnavn eller del | Beskrivelse |
---|---|
PersonCivilRegistrationIdentifier | CPR nummer |
...Identifier | Feltet identificerer en entitet, typisk en unik identifikation i form af en GUID eller et løbenummer. |
...TypeIdentifier | Felter med dette navn refererer til DFDG udstillede kodelister, der typisk udstilles vi CodeListService. Navnet på feltet bør så vidt muligt være det samme som navnet på kodelisten, hvor den tilhørende kodeliste hedder ...TypeIdentifierCodeList. Se Den gode kodeliste |
...Code | Feltet angiver en type af et element via en kodeliste eller enumerator. Kodelister/enumeratorer bør typisk anvende Code i navnet. |
...DateTime | Dato og tidsangivelse |
...Date | Dato angivelse |
...Name | Feltet er af typen string og indeholder et navn |
...Flag | Feltet er af typen boolean (true/false), navnet ... navnet skal tydeligt angive hvad true betyder. Normal vil true betyde at det navnet angiver gælder. Kan f.eks. sikres ved at skrive Is... eller Has... |
IncidentDateTime | Tidspunkt hvor hændelsen er indtruffet. |
DFDGRegistrationDateTime | Tidspunkt hvor hændelsen/data er registreret i DFDG |
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.
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:
Outputparametre:
Normalt returneres ID på entiteten der arbejdes med, under oprettelse returneres ID på den oprettede entitet:
Nedarvning i servicerequest
De obligatoriske metadata i kaldet kan findes under STARs sikkerhedsmodel