In this release

New batch create and update axioms endpoints are introduced.

New functionality

Batch endpoints

In order to speed up the onboarding process (creating Real Estate Core axioms), new endpoints for batch create and batch update operations are added:

  • POST /json/actuators
  • PUT /json/actuators
  • POST /actuators
  • PUT /actuators
  • POST /json/sensors
  • PUT /json/sensors
  • POST /sensors
  • PUT /sensors
  • POST /json/devices
  • PUT /json/devices
  • POST /devices
  • PUT /devices
  • POST /json/assets
  • PUT /json/assets
  • POST /assets
  • PUT /assets
  • POST /json/rooms
  • PUT /json/rooms
  • POST /rooms
  • PUT /rooms
  • POST /json/storeys
  • PUT /json/storeys
  • POST /storeys
  • PUT /storeys
  • POST /json/buildingcomponents
  • PUT /json/buildingcomponents
  • POST /buildingcomponents
  • PUT /buildingcomponents
  • POST /json/realestatecomponents
  • PUT /json/realestatecomponents
  • POST /realestatecomponents
  • PUT /realestatecomponents
  • POST /json/realestates
  • PUT /json/realestates
  • POST /realestates
  • PUT /realestates
  • POST /json/aliasnamespaces
  • PUT /json/aliasnamespaces
  • POST /aliasnamespaces
  • PUT /aliasnamespaces

Batch endpoints accepts json array of serialized axioms and returns response of the following format:

{
   “saved”: [
     “3dc774eb-9cba-430d-8a2d-2b39e71e0266“,
     “d0277015-fe2c-4565-a297-6661a3ae29b1“
   ],
   “failed”: [],
   “errors”: {},
   “totalSaved”: 2,
   “totalFailed”: 0,
   “totalProcessed”: 2
}

Where:

  • saved – the array of successfully saved axioms;
  • failed – the array of failed axioms (with generated ‘id’ property);
  • errors – map that contains errors of each failed axiom;
  • totalSaved – total number of saved axioms;
  • totalFailed – total number of failed axioms;
  • totalProcessed – total number of processed axioms.

Important things to pay attention to:

  • Batch endpoints to work with devices accepts array only of the same class (either only Devices, or only Sensors, or only Actuators);
  • Batch endpoints to work with building components accepts array only of the same class (either only Rooms, or only Storeys, or etc…);
  • After batch creation of devices is finished, there might be a small delay of up to a couple minutes until they are all ready to send or receive Edge messages (until they have all been registered in Azure Iot Hub)
  • Each batch endpoint may accept up to 1000 axioms in one batch.

Breaking changes

None.

Fixes and minor updated

Page query parameter improvements

  • page – parameter is not required anymore, its default value is equal to ‘0’;
  • size – parameter is not required anymore, its default value is equal to ‘50’;
  • size – maximum parameter value is limited to the value equal ‘3000’.

Error response codes

There are a number of improvements in the API error handling process. Some of response codes were changed to more precise ones:

  • in case of expired JWT token – ‘401 – Unauthorized’ response will be returned;
  • in case of incorrect request query – ‘409 – Conflict’ response will be returned;
  • in case of missing axioms – ‘404 Not Found’ response will be returned.