Klargjør om det er valgfritt å støtte filtrering av listeresultater?

[petterreinholdtsen]

---

       Prosjekt  NOARK 5 Tjenestegresesnitt
       Kategori  Noark 5.5.0 TG versjon 1.0
    Alvorlighet  protest
   Meldingstype  trenger klargjøring
Brukerreferanse  pere@hungry.com
    Dokumentdel  6.1.1.4
     Sidenummer  24
    Linjenummer  234

---

Beskrivelse

I https://github.com/petterreinholdtsen/noark5-tester/issues/36 ble det klart for meg at det er mulig å lese spesifikasjonen dithen at det er valgfritt om en vil støtte OData-filtrering eller ikke. Jeg har alltid lest spesifikasjonen dithen at endel filterparameter skal støttes for alle lister med instanser, men ser hvordan teksten kan tolkes til å tro at all filtrering er valgfri. Det står for eksempel under "Finne objekter (Read)" i kapittel 6 at "De ressurser som støtter filter skal annonserer dette under _links med templated=true og parametre som kan brukes til dette i href." Det kan tolkes til å tro at det er opp til leverandør om de vil støtte filtrering, og kun hvis det er støttet så skal templated=true brukes. Tolkningen forsterkes av formuleringen "Alle lister med data bør støtte søk og filtrering." i samme avsnitt. Lenger ned under "Nivå på filter" står det derimot at "Nivå basis"-filtrering er påkrevd og innebærer støtte for "Filter på direkte felter" og "Filter på en-til-en gruppe relasjoner (blant annet kodelister)".

Min tolkning er at filtering er påkrevd for lister med data, mens søk (aka $search) og "Nivå utvidet" er valgfritt). Formuleringen om at templated er valgfri er ment å henvise til de endepunktene som ikke er lister og ikke kan forventes å støtte filtrering, som endepunktet bak relasjonsnøkkel https://rel.arkivverket.no/noark5/v5/api/metadata/ eller https://rel.arkivverket.no/noark5/v5/api/admin/system, samt enkeltinstanser. Hvis dette er riktig tolkning så bør vi forsøke å justere formuleringene i teksten for å gjøre dette mer klart.

Ønsket endring

Endre formuleringer i kapittel 6 under "Finne objekter (Read)" til å gjøre det klart hvilken funksjonalitet som er påkrevd.

[tsodring]

Jeg er enig med dette. Det har alltid vært klar for meg at de fleste listeendepunktene skal støtte filtrering med OData. Det er kanskje viktig å huske at NOARK 5 Tjenestegresesnitt ikke er en OData implementasjon, men bruker OData syntaks osv. OData kanskje lar det være leverandør avhengig om OData skal være på et endepunkt eller ikke. NOARK 5 Tjenestegresesnitt er kanskje en "opinionated approach" til tolkning av Noark 5 og da er det viktig at den tar stilling til ting slik at kunder slipper å sette seg inn i så mye. Dette er et godt eksempel at NOARK 5 Tjenestegresesnitt tar inn funksjonalitet som er nyttig og utelukker det der det ikke er hensiktsmessig. Feks er $metadata noe fra OData som ikke er tatt inn, selv om det er nyttig.

Det er fint at spesifikasjonen blir tydeligere.

[petterreinholdtsen]

Det kan være nyttig å ta med seg at N5TG-klienten for epostimport jeg har skrevet forutsetter at ODAta-filtrering fungerer for å finne om en eposttråd allerede er i arkivet eller ikke, slik at nye epost legges inn i riktig mappe ved mottak. Slik funksjonalitet blir umulig hvis basal OData-filtrering ikke er tilgjengelig fra et N5TG-grensesnitt.

API-klienter får et API det er umulig å bruke til en rekke bruksområder hvis en må bla gjennom alle sidene med alle instaner i en liste for å finne de få en skal operere på.

-- Vennlig hilsen Petter Reinholdtsen

[petterreinholdtsen]

Foreslår følgende endring i teksten, fra

Feltet «templated» er valgfritt og verdien skal antas å være «false» hvis det ikke finnes. Typiske parametre er $filter, $top, $skip og $orderby. Alle lister med data bør støtte søk og filtrering.

til

De endepunkter som ikke støtter filtering trenger ikke oppgi feltet «templated» og feltverdien antas å være «false» når feltet ikke finnes. Typiske parametre er $filter, $top, $skip og $orderby. Alle lister med data skal støtte filtrering, jamfør kravlisten under. Lister bør også støtte søk.

[petterreinholdtsen]

Den opprinnelige formuleringen om templated ble lagt inn i 1177f9bb7fc66a6963d714ddb0e3c37914d9100c .

[petterreinholdtsen]

Temaet ble diskutert på dagens redaksjonsmøte og formuleringen i spesifikasjonen ble oppdatert for å gjøre det klarere hvilke Odata-notasjoner som er påkrevd.