FORM-REST udstiller forretningsreferencemodellen (FORM) som RESTful web service. Her følger en dokumentation af de forskellige funktioner, der er tilgængelige i FORM-REST.
Opgavenøgle
Man kan både hente hele Opgavenøglen med samtlige serviceområder, hovedområder, opgaveområder og opgaver, og hente delelementer som f.eks. et
enkelt hovedområde, med tilhørende opgaveområder.
For at hente den fulde Opgavenøgle skriver man følgende URL:
- http://api.form-online.dk/resources/ (Hent Fuld opgavenøgle)
- http://api.form-online.dk/resources/?soegeord=ja (Hent fuld opgavenøgle med søgeord)
Ønsker man at hente dele af Opgavenøglen skal man anvende to parametre: FormIndgang og dybde.
"FormIndgang" angiver FORM-nummeret på det element, man ønsker at hente. Formatet for hhv. serviceområder, hovedområder, opgaveområder
og opgaver er: "00", "00.00", "00.00.00", "00.00.00.00".
"dybde" angiver hvor mange niveauer, man ønsker at hente sammen med det specificerede element. Angiver man FormIndgang og ikke nogen dybde,
returneres samtlige niveauer under det angivne element. Angiver man dybde=0 returneres det specificerede element i et særligt kort format. Ligeledes
returneres niveauet under sidste niveau altid i kort format.
Her følger et par eksempler:
- http://api.form-online.dk/resources/10?dybde=0 (Hent serviceområde 10 med dybde 0)
- http://api.form-online.dk/resources/10?dybde=1 (Hent serviceområde 10 med dybde 1)
- http://api.form-online.dk/resources/10?dybde=2 (Hent serviceområde 10 med dybde 2)
- http://api.form-online.dk/resources/37.25.30 (Hent serviceområde 10 med dybde 3)
Eksempel 1, 2 og 3 henter alle serviceområde 10. Eksempel 1 henter i kort format uden hovedområder. Eksempel 2 henter i fuldt format inklusive
hovedområder i kort format. Eksempel 3 henter serviceområdet og tilknyttede hovedområder i fuldt format, samt opgaveområder i kort format.
Eksempel 4 henter opgaveområdet 37.25.30 i fuldt format inklusive tilknyttede opgaver i fuldt format.
Man kan også kalde "resources" med en UUID i stedet for et FORM-nummer. Syntaksen er helt identisk med ovenstående:
- http://api.form-online.dk/resources/f3295ba5-0915-11e0-8366-0050c2490048?dybde=1 (Hent serviceområde 10 med dybde 1 via UUID)
Bemærk at FORM søgeord ikke leveres med som default, da de fylder meget. Ønsker man at få søgeord med i resultatet, skal man tilføje parameteren "soegeord" med værdien "ja". F.eks.
- http://api.form-online.dk/resources/10?dybde=1&soegeord=ja (Hent serviceområde 10 med dybde 1 inklusive søgeord)
Søgning
Fritekstsøgningen fra FORM-Online er også til rådighed over REST via følgende URL:
- http://api.form-online.dk/resources/search?tekst=miljø (Udfør søgning på søgeordet miljø)
Søgeresultatet returneres som en liste af FORM-elementer rangeret efter, hvor godt brugerens søgeord matcher de pågældende elementer. For hvert FORM-element er skemaet næsten identisk med skemaet for den almindelige hentning af FORM-elementer. Det vil sige, at hvert FORM-element er repræsenteret med sine vigtigste attributter (VersionIdentifikator, OprettetDato, NavnTekst, BeskrivelseTekst og NummerIdentifikator). Forskelle fra standardskemaet:
- Eventuelle underelementer returneres ikke.
- Matchende søgeord i NavnTekst eller BeskrivelseTekst er opmærket med et span-tag.
Som på FORM-Online er det i FORM-REST også muligt at angive forskellige parametre, der styrer mere præcist, hvordan søgningen udføres.
- scope: "forvaltning" (default), "opgave" (default), "service og hovedområder" (default)
- element: "navn" (default), "stikord" (default), "beskrivelse"
- synonyms: "dictionary" (default), "synonyms"
Parameteren "scope" angiver, hvilke FORM-elementer, der skal søges i. Man kan ved at angive én eller flere scope-værdier søge i ét eller flere elementer på en gang, f.eks.:
- http://api.form-online.dk/resources/search?tekst=miljø&scope=forvaltning&scope=servicehoved (Udfør søgning på søgeordet miljø med bestemt scope)
Parameteren "element" angiver, hvilke attributter, der skal søges i. Man kan angive én eller flere, f.eks.:
- http://api.form-online.dk/resources/search?tekst=miljø&element=stikord&element=beskrivelse (Udfør søgning i beskrivelse og stikord på søgeordet miljø)
Parameteren "synonyms" angiver om der skal udføres en semantisk smal ("dictionary") eller bred ("synonyms") søgning. Standardsøgningen (smal søgning) søger på bøjningsudvidelser og sammemsatte ord. Angiver man en bred søgning, søges der dertil også på synonymer.
Hvis man ikke angiver nogen værdi for en given parameter, anvender søgningen default-indstillingen (som markeret i listen ovenfor).
NB! Søgning med resultater returneret via JSONP er endnu IKKE understøttet. NB! Søgeord returneres IKKE i søgeresultatet fra en fritekstsøgning.
Opslag i ældre (arkiverede) versioner af FORM
Alle operationer i REST-API'et foregår som udgangspunkt i nyeste publicerede version. Versionsnummeret på nyeste version står både angivet her på siden (øverst i højre hjørne) samt på alle resultater, der returneres fra API'et.
Det er muligt at tilgå ældre/arkiverede versioner af FORM, dog er søgningen kun tilgængelig for nyeste version. Ældre versioner kan tilgås ved at tilføje en "version"-parameter til sin URL.
Følgende arkiverede versioner er tilgængelige:
- 2.1
- 2.2
- 2.3
- 2.4
- 2.5
- 2.6
- 2.7
- 2.8
- 2.9
- 2.10
- 2.11
- 2.12
- 2.13
- 2.14
- 2.15
- 2.16
- 2.17
- 2.18
Prøv f.eks.
- http://api.form-online.dk/resources/05.05.55?version=2.1 (Hent opgaveområde 05.05.55 fra version 2.1 af FORM)
Versionsnummerering
Her følger en kort forklaring af betydningen af de enkelte sekvenser i versioneringen af FORM:
- x.x (1. sekvens) en ændring i første sekvens afspejler en væsentlig ændring i strukturen i FORM
- x.x (2. sekvens) en ændring i anden sekvens afspejler mindre ændringer i strukturen i FORM
- x.x.x (3. sekvens) en ændring i tredje sekvens afspejler alene opdateringer af relaterede data – myndigheder, lovgivning, finanslov og søgeord (Bemærk, at FORM-online altid kun viser de 2 første sekvenser)
Skema
Skemaet for den XML, som returneres er specificeret i følgende skema:
- http://api.form-online.dk/schema/Form.xsd (Hent XML-skema for REST-resultater)
Ligeledes er der defineret et skema for nuværende (og fremtidige) funktionskald tilgængelige via FORM-REST:
- http://api.form-online.dk/schema/FormOperationer.xsd (Hent XML-skema for FORM-operationer)
JSONP
Data er også tilgængelige i JSON-format via JSONP på eksempelvis følgende URL:
- http://api.form-online.dk/resources/jsonp/10?callback=? (Hent serviceområde 10 via JSONP)
SKOS
FORM er også tilgængelig i RDF-SKOS. Tilgængelig udgaver er listet nedenfor.