Dokumentation af Web API

Find fisken web servicens API er beskrevet i nedenstående tabel.

Et af formålene med Find fisken web servicen er at eksperimentere med, hvordan miljødata kan udstilles. Af denne grund er der mulighed for at nedenstående Web API løbende ændres.

Baseadresse: http://oiorest.dk/findfisken

Resource URI Method Repræsentation Status Beskrivelse
Arter /arter?q={del af navn} GET XML beskrevet i arter.xsd 200, 405, 500 Modtag liste over arter
Art /arter/{artsnr} GET XML beskrevet i art.xsd 200, 404, 405, 500 Modtag information om en art
Stationer /stationer?{søgekriterie} GET XML beskrevet i stationer.xsd 200, 405, 500 Modtag liste over stationer der opfylder søgekriteriet
Stationer /stationer/{svbredde},{svlængde};{nøbredde},{nølængde}?{søgekriterie} GET XML beskrevet i stationer.xsd 200, 405, 500 Modtag liste over stationer, hvis placering ligger i rektanglet angivet  sydvestlige koordinat og en nordøstlig koordinat. Koordinattype angives ved at sætte queryparameteren koordinattype til enten etrs89 eller wgs84. Default er wgs84. Punktum som decimalpunkt.
Station /stationer/{stationsnr} GET XML beskrevet i station.xsd 200, 405, 500 Modtag information om station
Stations feltprøver stationer/{stationsnr}/feltprøver?{søgekriterie} GET XML beskrevet i feltprøver.xsd 200, 405, 500 Modtag liste over en stations feltprøver der opfylder søgekriteriet
Feltprøver /feltprøver?{søgekriterie} GET XML beskrevet i feltprøver.xsd 200, 405, 500 Modtag liste over feltprøver der opfylder søgekriteriet
Feltprøver /feltprøver/{svbredde},{svlængde};{nøbredde},{nølængde}?{søgekriterie} GET XML beskrevet i feltprøver.xsd 200, 405, 500 Modtag liste over feltprøver, hvis station ligger i rektanglet angivet  sydvestlige koordinat og en nordøstlig koordinat. Koordinattype angives ved at sætte queryparameteren koordinattype til enten etrs89 eller wgs84. Default er wgs84. Punktum som decimalpunkt.
Feltprøve stationer/{stationsnr}/feltprøver/{dato} GET XML beskrevet i feltprøver.xsd 200, 405, 500 Modtag information om en feltprøve

Søgekriterie til resourcen stationer

vandomraadenr={vandomraadenr}&kommunenr={kommunenr}&q={navn eller del af navn}

Søgekriterie til resourcen observationer

vandomraadenr={vandomraadenr}&kommunenr={kommunenr}&q={navn eller del af navn}&artsnr={artsnr}&stationsnr={stationsnr}&start={startdato}&slut={slutdato}

Datoformat

yyyymmdd. Eksempel 20071231 for den 31. descember 2007.

JSON format

Find fisken servicens ressourcer returneres default i xml. Hvis repræsentationen ønskes i JSON tilføjes url'en suffixet .json. JSON står for JavaScript Object Notation og er specielt velegnet i forbindelse med udvikling af JavaScript klienter, som f.eks. web sider. I stedet for /arter/1085 skrives /regioner/1085.json.

JSONP format

JSONP er et mekanisme til at omgå cross-domain kommunikationsproblemet i en browser: Hvis du fra JavaScript kode i en browser forsøger at forespørge på data fra et andet domæne, vil du få en sikkerhedsfejl. JSONP mekanismen går i korte træk ud på at dynamisk loader et scripttag i et html dokument, hvor src attributen udpeger de ønskede data. De ønskede data returneres, formateret som et JavaScript funktionskald med data som parameter. Mekanismen er lidt svært at beskrive uden at vise en del html og JavaScript kodestumper. Det er der ikke plads til her, men du kan læse en god beskrivelse her

Hvis du f.eks. vil have fat i oplysninger om Flodlampreten fra din browserapplikation kan du bruge http://oiorest.dk/findfisken/arter/106.json?callback=visfisk til at kalde visfisk funktionen i din JavaScript applikation med fiskens information formateret i JSON argument.

 

Stationer og observationer præsenteret på kort

Alle Find fisken web servicens station og observation ressourcer kan præsenteres på kort. I en browser vil denne html præsenterer dem på et kort. Der kan vælges mellem 3 forskellige korttyper: Kort & Matrikelstyrelsens, Googles eller Microsofts. Kort & Matrikelstyrelsens kort vælges ved at anvende suffixet kms, Googles gm og Microsofts msm.

Kompression

Hvis den anvendte netværksforbindelse er langsom (lille båndbredde) og den datamængde der ønskes fra Danmark servicen er stor, kan klientapplikationen anmode om at svaret (response) komprimeres. Dette gøres ved at indsætte følgende http header i requestet:

Accept-Encoding: gzip, deflate

Herved reduceres størrelsen af et typisk XML dokument til 1/10.

Statuskoder

Alle statuskoder er inkluderet i HTTP Status header. De anvendte statuskoder er :

  • 200: Succes
  • 400: Forkert formatteret request
  • 404: Resource findes ikke
  • 405: Den anvendte metode er  ikke tilladt
  • 500: Application fejl