KS KommIT tjenestegrensesnittNOARK5 REST
REST-grensesnitt for NOARK5 versjon 4.0 (forslag)
HATEOAS prinsipper er forsøkt fulgt http://stateless.co/hal_specification.html
Foreløpig skjema som benyttes i application/vnd.noark5-v4+json og application/vnd.noark5-v4+xml
- http://skjema.kxml.no/arkivverket/noark5/v4.0/metadata/metadata.xsd
- http://skjema.kxml.no/arkivverket/noark5/v4.0/moeteogutvalgsbehandling/moeteogutvalgsbehandling.xsd
- http://skjema.kxml.no/arkivverket/noark5/v4.0/arkivstruktur/arkivstruktur.xsd
- http://skjema.kxml.no/arkivverket/noark5/v4.0/sakarkiv/sakarkiv.xsd
Rel attributtet er dokumentert på disse sidene og beskriver de semantiske relasjonene(lenkene) som en klient bør håndtere.
Første respons til API er beskrevet under Api og gir lenker videre til andre ressurser og mulige operasjoner
Prototyper serverside
https://github.com/nxc/prototype-noark-web-service (Java)
https://github.com/Arkitektum/N5-net (.Net) – kjører også på http://n5test.kxml.no/api/ og er brukt i eksemplene på disse sidene
https://github.com/Arkitektum/N5-prototype (.Net utgår)
https://github.com/Arkitektum/n5-java (Java)
Filtrering
Det er forslag om å benytte oData filtrering på alle lister(Collections) http://docs.oasis-open.org/odata/odata/v4.0/os/part1-protocol/odata-v4.0-os-part1-protocol.html#_Toc372793691
Støtte for spørring med:
- $filter
- $orderby
- $top
- $skip
- $search – Fritekstsøk – (Obligatorisk 5.9.6)
Operatorer som bør støttes i $filter:
| eq | Equal | tittel eq ‘Byggesak’ |
| ne | Not equal | tittel ne ‘Personalsak’ |
| gt | Greater than | Price gt 20 |
| ge | Greater than or equal | Price ge 10 |
| lt | Less than | Price lt 20 |
| le | Less than or equal | Price le 100 |
Logiske operatorer
| and | Logical and | Price le 200 and Price gt 3.5 |
| or | Logical or | Price le 3.5 or Price gt 200 |
Utvalg av felter
Begrenses til aktuelt returobjekt. For eksempel ved filtrering av mapper så kan en velge å filtrere på felt i mappe objektet ihht skjema http://rel.kxml.no/xsd/arkivstruktur.xsd
Det samme gjelder $orderby
$search er implementasjonsavhengig.
Tilgang og skjerming
Søkeresultat skal ta hensyn til tilgangen til dokumentene i kjernen og til skjerming av opplysninger. (5.9.11, 5.9.12)
Eksempler
Ved å navigere til arkivstruktur så vil responsen fra denne blant annet inneholde lenke til Arkiv som med templated=true og angivelse av nøkkelord i uri annonserer hvilke muligheter klient har for å gjøre søk og filtreringer.
GET http://n5test.kxml.no/api/Arkivstruktur
Content-Type: application/vnd.noark5-v4+json
[
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkiv",
"templated": true,
"templatedSpecified": true
},....
]
Klienten bruker template uri til å fylle inn parametre for søk. I dette tilfellet de 5 første arkiv som har tittel lik ‘test’
GET http://localhost:49708/api/arkivstruktur/Arkiv?$top=5&$filter=tittel eq ‘test’
Content-Type: application/vnd.noark5-v4+json
[
{
"tittel": "test arkiv 12345",
"beskrivelse": null,
"arkivstatus": null,
"dokumentmedium": null,
"oppbevaringssted": null,
"opprettetDatoSpecified": false,
"opprettetAv": null,
"avsluttetDatoSpecified": false,
"avsluttetAv": null,
"systemID": "12345",
"_links": [
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/12345",
"rel": "self",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/12345/arkivdel{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivdel",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/12345/ny-arkivdel",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivdel",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/12345/arkivskaper{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivskaper",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/12345/ny-arkivskaper",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivskaper",
"templatedSpecified": false
}
]
},
{
"tittel": "test arkiv 234",
"beskrivelse": null,
"arkivstatus": null,
"dokumentmedium": null,
"oppbevaringssted": null,
"opprettetDatoSpecified": false,
"opprettetAv": null,
"avsluttetDatoSpecified": false,
"avsluttetAv": null,
"systemID": "234",
"_links": [
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/234",
"rel": "self",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/234/arkivdel{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivdel",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/234/ny-arkivdel",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivdel",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/234/arkivskaper{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivskaper",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/234/ny-arkivskaper",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivskaper",
"templatedSpecified": false
}
]
},
{
"tittel": "test arkiv ae07483d-26e0-494f-b005-1b441ddcf47a",
"beskrivelse": null,
"arkivstatus": null,
"dokumentmedium": null,
"oppbevaringssted": null,
"opprettetDatoSpecified": false,
"opprettetAv": null,
"avsluttetDatoSpecified": false,
"avsluttetAv": null,
"systemID": "ae07483d-26e0-494f-b005-1b441ddcf47a",
"_links": [
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/ae07483d-26e0-494f-b005-1b441ddcf47a",
"rel": "self",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/ae07483d-26e0-494f-b005-1b441ddcf47a/arkivdel{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivdel",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/ae07483d-26e0-494f-b005-1b441ddcf47a/ny-arkivdel",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivdel",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/ae07483d-26e0-494f-b005-1b441ddcf47a/arkivskaper{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivskaper",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/ae07483d-26e0-494f-b005-1b441ddcf47a/ny-arkivskaper",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivskaper",
"templatedSpecified": false
}
]
},
{
"tittel": "test arkiv 4e5773d9-d3d7-4b64-947c-9865caff0fd0",
"beskrivelse": null,
"arkivstatus": null,
"dokumentmedium": null,
"oppbevaringssted": null,
"opprettetDatoSpecified": false,
"opprettetAv": null,
"avsluttetDatoSpecified": false,
"avsluttetAv": null,
"systemID": "4e5773d9-d3d7-4b64-947c-9865caff0fd0",
"_links": [
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/4e5773d9-d3d7-4b64-947c-9865caff0fd0",
"rel": "self",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/4e5773d9-d3d7-4b64-947c-9865caff0fd0/arkivdel{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivdel",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/4e5773d9-d3d7-4b64-947c-9865caff0fd0/ny-arkivdel",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivdel",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/4e5773d9-d3d7-4b64-947c-9865caff0fd0/arkivskaper{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivskaper",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/4e5773d9-d3d7-4b64-947c-9865caff0fd0/ny-arkivskaper",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivskaper",
"templatedSpecified": false
}
]
},
{
"tittel": "test arkiv 65abe497-61f7-4def-bf3a-e1cea847ddcf",
"beskrivelse": null,
"arkivstatus": null,
"dokumentmedium": null,
"oppbevaringssted": null,
"opprettetDatoSpecified": false,
"opprettetAv": null,
"avsluttetDatoSpecified": false,
"avsluttetAv": null,
"systemID": "65abe497-61f7-4def-bf3a-e1cea847ddcf",
"_links": [
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/65abe497-61f7-4def-bf3a-e1cea847ddcf",
"rel": "self",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/65abe497-61f7-4def-bf3a-e1cea847ddcf/arkivdel{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivdel",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/65abe497-61f7-4def-bf3a-e1cea847ddcf/ny-arkivdel",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivdel",
"templatedSpecified": false
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/65abe497-61f7-4def-bf3a-e1cea847ddcf/arkivskaper{?$filter&$orderby&$top&$skip&$search}",
"rel": "https://rel.arkivverket.no/noark5/v4/arkivskaper",
"templated": true,
"templatedSpecified": true
},
{
"uri": "http://localhost:49708/api/arkivstruktur/Arkiv/65abe497-61f7-4def-bf3a-e1cea847ddcf/ny-arkivskaper",
"rel": "https://rel.arkivverket.no/noark5/v4/ny-arkivskaper",
"templatedSpecified": false
}
]
}
]