The API is built on a protocol that is named Open Data Protocol (OData). It is an open protocol that describes a REST API for sharing and modifying data in a system. Landax API supports OData version 2 and 4.

Clients

There are many clients supporting OData. See an overview here: https://www.odata.org/libraries/

Landax also provides a .NET client running on .NET Framework 4.8. It is available in NuGet and is named "Landax.Client". See documentation for it here: https://www.nuget.org/packages/Landax.Client/#readme-body-tab

Supported formats

The API supports JSON and AtomXML formats, in addition to HTML from a web browser and ExcelXML for older versions of Excel. The format can be set via the HTTP header "Accept", for instance Accept: application/json , or via URL as query string, ?$format=json .

Required HTTP Headers

  • Accept: application/json or application/xml or text/html.
  • Authorization: Bearer token
  • DataServiceVersion: 2.0 or 4.0 (4.0 recommended for new integrations)

The OData protocol

The OData protocol is well documented on odata.org. Below here, we will summarize the most basic with OData 4.0 and JSON. For ATOM, OData 2.0 or other things that are not mentioned here, see the OData documentation at odata.org.

Get data

Getting data is done via HTTP GET på adresse /odata/v{$version}/[$modelKey}, for example 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..}
  ],
}


Following parameters is supported as query strings.

  • $top=123 : max amount of returned rows
  • $skip=0 : amount of rows to skip - use in cooperation with $top to make pagination
  • $filter=Subject contains "test" - see Data filters
  • $filterid=2 - Id to stored Datafilter
  • $select=Id,Subject - comma separated list over fields to fetch
  • $expand=Tasks,Documents - comma separated list over relations to fetch
  • $format=json - normally used to test from browser, clients should use header Accept 
  • $callback=jsonp - used for JSONP requests

Get single record

Getting a single record is done via HTTP GET on /odata/v{$version}/{$modelKey}({$id}) - for example https://company.landax.no/odata/v24/Incident(123). Same format as fetching list of data. value  from response will not be an array, but an object.

Create new record

Creating is done via HTTP POST on same address as fetching data set. The record is sent as an object.

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...
}

The API will respond with the newly created object, in the same manner as when fetching a single record. Response status will be 201 Created.

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

{ ..incident data.. }

Modify record

Modifying data is done via HTTP PUT to same address as fetching single record. MERGE or PATCH also works, and will do the same thing. Request is same as creating new object. The response status will be 204 No Content, unless header  Prefer: return=representation  is specified, then it will return the object as for fetching single record.

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.. }

gives

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

This is no error, all HTTP statuses starting with 2 is "success" statuses. It just indicates that there is no returned data, since  Prefer: return=representation was not specified.

Deleting data

Deleting data is done by sending HTTP DELETE to same address as fetching and updating record. HTTP Response will be either 200 OK or 204 No Content. No data will be returned.

  • No labels