APIet er bygget på en protokoll som heter Open Data Protocol (OData). Det er en åpen protokoll som beskriver et REST-basert API for deling og modifisering av data i et system. Landax API støtter både OData versjon 2 og versjon 4.

Klienter

Det finnes mange klienter som støtter OData. Det finnes en oversikt her: https://www.odata.org/libraries/

Landax har også en egen .NET klient som kjører på .NET Framework 4.8. Denne finnes på NuGet og heter «Landax.Client». Se dokumentasjon på denne her: https://www.nuget.org/packages/Landax.Client/#readme-body-tab

Støttede formater

APIet støtter JSON og AtomXML formater, i tillegg til HTML fra nettleser og ExcelXML for eldre versjoner av Excel. Format kan settes via HTTP-headeren «Accept», for eksempel Accept: application/json , eller via URL som query string, ?$format=json .

Påkrevde HTTP Headers

  • Accept: application/json eller application/xml eller text/html.
  • Authorization: Bearer token
  • DataServiceVersion: 2.0 eller 4.0 (4.0 absolutt anbefalt for nye integrasjoner)

OData protokollen

OData protokollen har en omfattende dokumentasjon på odata.org. Her sammenfatter vi det mest grunnleggende ved bruk av OData 4.0 og JSON. For Atom eller OData 2.0, eller andre ting som ikke er nevnt her, se OData dokumentasjonen på odata.org.

Henting av datasett

Henting av data gjøres via HTTP GET på adresse /odata/v{$version}/[$modelKey}, for eksempel https://company.landax.no/odata/v24/Incidents.

GET /odata/v24/Incidents HTTP/1.1
Host: company.landax.no
DataServiceVersion: 4.0
Accept: application/json
Authorization: Bearer asdf-qwerty-asdf-qwerty

will respond with

HTTP/1.1 200 OK
Content-Type: application/json
..some more headers..

{
  "@odata.context": "https://company.landax.no/odata/v24/$metadata#Incidents",
  "value": [
    { ..incident data..},
    { ..incident data..}
  ],
}


Følgende parametere er støttet som query strings.

  • $top=123 : antall rader som skal returneres
  • $skip=0 : antall rader som skal hoppes over - denne brukes i samarbeid med $top for å lage en sidevisning
  • $filter=Subject contains "test" - se Datafilter
  • $filterid=2 - Id til lagret Datafilter
  • $select=Id,Subject - kommaseparert liste over felter som skal hentes ut
  • $expand=Tasks,Documents - kommasepartert liste over relasjoner som skal hentes ut
  • $format=json - brukes stort sett for å teste fra nettleser, klienter bør sende Accept 
  • $callback=jsonp - brukes for JSONP requests

Henting av enkelt-oppføring

Henting av enkelt-oppføring gjøres via HTTP GET på adresse /odata/v{$version}/{$modelKey}({$id}) - for eksempel https://company.landax.no/odata/v24/Incident(123). Ellers følges samme format som henting av datasett. value  vil ikke være et array, men et objekt.

Opprette ny oppføring

Oppretting foregår mot HTTP POST på samme adresse som for uthenting av datasett. Oppføringen sendes som objekt.

POST /odata/v24/Incidents HTTP/1.1
Host: company.landax.no
DataServiceVersion: 4.0
Accept: application/json
Authorization: Bearer asdf-qwerty-asdf-qwerty

{
  "Subject": "Test incident",
 ...incident data...
}

API vil respondere med objektet som ble opprettet, på samme måte som for henting av enkelt-oppføring. Respons vil være "201 Created".

HTTP/1.1 201 Created
...headers...

{ ..incident data.. }

Endre oppføring

Endring av data foregår ved en HTTP PUT mot samme adresse som henting av enkelt-oppføring. MERGE og PATCH fungerer også, og vil gjøre samme nytte. Request er samme som ved oppretting. Respons vil være 204 No Content dersom man ikke sender header Prefer: return=representation  som vil sørge for at data returneres tilbake på samme måte som ved oppretting.

PUT /odata/v24/Incident(123) HTTP/1.1
Host: company.landax.no
DataServiceVersion: 4.0
Accept: application/json
Authorization: Bearer asdf-qwerty-asdf-qwerty

{ ..incident data.. }

gir

HTTP/1.1 204 No Content
...headers...

Det er altså ingen feil, alle HTTP-koden som starter med 2 er vellykket-koder. Men den bare indikerer at det ikke sendes noe innhold som svar. Om man da legger på Prefer: return=representation får man hele modellen på samme måte som ved oppretting.

Sletting av data

Sletting av data gjøres ved å sende en HTTP DELETE mot samme adresse som henting og endring av oppføring. HTTP respons vil være 200 OK eller 204 No Content, og ingen data vil sendes.

  • No labels