Dropp støtte for XML-varianten av API-et?

[petterreinholdtsen]

Dette er en kopi av mangelmelding sendt inn til Arkivverket, se også https://github.com/petterreinholdtsen/noark5-tester/blob/master/mangelmelding/sendt/2018-11-27-drop-xml-format.md .

---

       Prosjekt  Noark 5 Tjenestegresesnitt
       Kategori  Versjon 1.0 beta
    Alvorlighet  kommentar
   Meldingstype  utelatt
Brukerreferanse  pere@hungry.com
    Dokumentdel  6.1.1.2
     Sidenummer  12
    Linjenummer  n/a
Innsendingsdato  2018-11-27

---

Denne teksten er del av en samling innspill til Noark5-standarden tilgjengelig fra https://github.com/petterreinholdtsen/noark5-tester/.

Beskrivelse

Spesifikasjonen mangler en klar beskrivelse av hvordan REST-forespørsler som bruker XML skal se ut, og hvilket resultat de skal få tilbake. Det eneste eksempelet er i del 6.1.1.1 (Oppkobling og ressurslenker) på side 12, som viser hvordan relasjonslenker skal formatteres som XML.

Men spesifikasjon, demotjenesten på http://n5test.kxml.no/api/ og XML-eksempel på http://rel.kxml.no/noark5/v4/api/ er ikke enige om hvordan XML-lister med relasjoner skal se ut. Spesifikasjon og demotjeneste er like, mens XML-eksempelet er forskjellig fra dem.

Slik ser eksempelet på side 12 og http://n5test.kxml.no/api/ ut:

<Links xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.kxml.no/rest/1.0"&gt; <Links> <link> <rel>http://rel.kxml.no/noark5/v4/api/arkivstruktur&lt;/rel&gt; <href>http://n5test.kxml.no/api/arkivstruktur&lt;/href&gt; <type xsi:nil="true" /> <deprecation xsi:nil="true" /> <name xsi:nil="true" /> <title xsi:nil="true" /> </link> <link> <rel>http://rel.kxml.no/noark5/v4/api/sakarkiv&lt;/rel&gt; <href>http://n5test.kxml.no/api/sakarkiv&lt;/href&gt; <type xsi:nil="true" /> <deprecation xsi:nil="true" /> <name xsi:nil="true" /> <title xsi:nil="true" /> </link> </Links> </Links>

Merk hvordan denne har to identiske XML-tagger (Links) inne i hverandre. Hva er årsaken til at det brukes to identiske XML-tagger slik? En skulle tro det holder med et nivå.

Eksempelet på http://rel.kxml.no/noark5/v4/api/ har ikke duplikat-tagger, men derimot LinkListe som ytre XML-tag i stedet for Links:

<LinkListe xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.kxml.no/rest/1.0"&gt; <_links> <href>http://n5test.kxml.no//api/arkivstruktur&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/arkivstruktur&lt;/rel&gt; </_links> <_links> <href>http://n5test.kxml.no//api/sakarkiv&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/sakarkiv&lt;/rel&gt; </_links> <_links> <href>http://n5test.kxml.no//api/moeteogutvalgsbehandling&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/moeteogutvalgsbehandling&lt;/rel&gt; </_links> <_links> <href>http://n5test.kxml.no//api/administrasjon&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/administrasjon&lt;/rel&gt; </_links> <_links> <href>http://n5test.kxml.no//api/loggingogsporing&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/loggingogsporing&lt;/rel&gt; </_links> <_links> <href>http://n5test.kxml.no//api/rapporter&lt;/href&gt; <rel>http://rel.kxml.no/noark5/v4/api/rapporter&lt;/rel&gt; </_links> </LinkListe>

Hvilke av disse variantene er korrekte? Den med duplikatlenker eller den uten?

Spesifikasjonen mangler beskrivelse av hvordan objekter og lister skal formatteres i XML. Det er dermed uklart for de som skal utvikle REST-klienter og -tjenester hvordan informasjonen som skal utveksles skal være. Det enkleste for alle ville være om det kun var en entydig måte å snakke med API-et på, i stedet for to (JSON og XML). Hvorfor er det to ulike "dialekter" i spesifikasjonen?

Hvis XML skal være en del av API-definisjonen, så bør enten spesifikasjonen beskrive hvordan alle objekter og lister av objekter skal formateres i XML, eller så bør den inneholde en forklaring på hvordan JSON-strukturer kan omdannes til XML. Gitt at XML-formatteringen nok trenger navnerom-informasjon, mens JSON-formatteringen ikke trenger tilsvarende, så vil det ikke være mulig å automatisk omforme JSON til XML uten at det tilføres ekstra informasjon. Hvorvidt det er praktisk gjennomførbart eller ikke kommer an på hvor mange ulike navnerom som forventes brukt i XML-formatteringen.

Gitt at JSON-utgaven er tilstrekkelig og bedre beskrevet i spesifikasjonen enn XML, så er det kanskje like greit å droppe XML-dialekten? Alternativt så må det beskrives i detalj hvordan XML-utvekslingen for alle endepunktene skal se ut, og alle eksemplene på http://rel.kxml.no/noark5/ endres til å stemme overens med spesifikasjonen.

Ønsket endring

Dropp XML-utveksling fra API-spesifikasjonen, og bruk kun JSON. Fjern teksten på side 12-, fra "Alternativt som XML" til og med siste "".

[petterreinholdtsen]

Det er verdt å merke seg at hverken Nikita eller Evry har XML-støtte, så vidt jeg vet, og det finnes så vidt jeg vet ingen API-klienter som forventer XML-støtte. Det skulle dermed ikke være noen utviklingskostnad eller samvirkemulighet tapt ved å droppe XML-varianten.

[petterreinholdtsen]

Er det noen som kjenner til gode grunner til å beholde XML-varianten av protokollen?

XML-varianten kan jo uansett ikke brukes direkte til å lage deponiformat, så en API-klient som henter ut informasjon for deponering uansett må skrive om det som mottas til avleveringsformat, da endel felt som er attributter og "innbygging" i avleveringsformatet er relasjoner i API-et., og da har det i realiteten ikke noe å si om klienten mottar JSON eller XML.

[petterreinholdtsen]

Jeg ser denne mangelmeldingen er tildelt @hanber og @oivkru. Kan dere bidra med oppklaring? Er det noen argumenter for å beholde to protokoll-"dialekter", dvs. JSON og XML jeg ikke ser?

[petterreinholdtsen]

Etter mitt skjønn, gitt at dagens spesifikasjon mangler informasjon om XML-formattering av protokoll-utveksling for det meste av meldinger som kan sendes frem og tilbake mellom API-tjener og klient, og dagens tempo på forbedringer av spesifikasjonen, så vil det krever mellom 6 måneder og 2 år å få ferdig spesifikasjonen hvis alt som skal sendes mellom API-klient og -tjener skal beskrives som både XML og JSON. Spesielt siden JSON ikke trenger endel av feltene som XML krever (navnerom, url til skjema etc), slik at en må lage mekanikk rundt dette i tillegg til det som JSON trenger.

[petterreinholdtsen]

Å ha med XML-protokoll i spesifikasjonen gir ekstra utfordringer og at spesifiseringen tar ekstra tid, se for eksempel diskusjonen relatert til #61 og #78.

[PetterBAR]

Jeg mener at det viktige nå er å få på plass et tjenestegrensesnitt som er i synk med standarden og som sikrer en omforent og entydig bruk av det. Med tanke på hvor lang tid det tar å jobbe frem noe sånt, synes jeg det mest rasjonelle er kun å bruke JSON, og heller utnytte ressursene på det prekære og opplagte. Jeg har ikke nok kunnskap om XML vs. JSON i denne sammenhengen, men hvis det skulle vise seg at JSON ikke er tilstrekkelig, vil det vel ikke være en uoverkommelig jobb å ta utgangspunkt i det fungerende og lage en utvidet XML-variant To andre argumenter for JSON er for det første at det ikke er samsvar mellom eksemplene Petter R henviser til lenger opp, noe som krever oppklaring og ressurs- og tidsbruk, og for det andre at det neppe er et skrikende behov for en XML-variant ute i markedet.