In this release

ProptechOS now supports patching Axioms.

New functionality

Patching

Most axioms can now be patched via PATCH endpoints. Instead of replacing the whole object, a specific property can be manipulated, while leaving the rest of the object unchanged. It is a faster and more convenient way to perform simple updates.

Operations are performed according to JSON Patch standard (specified in RFC 6902 from the IETF).

New endpoints available:

  • PATCH /json/realestate/{id}
  • PATCH /json/realestatecomponent/{id}
  • PATCH /json/buildingcomponent/{id}/class/{class}
  • PATCH /json/room/{id}
  • PATCH /json/storey/{id}
  • PATCH /json/asset/{id}
  • PATCH /json/device/{id}
  • PATCH /json/sensor/{id}
  • PATCH /json/actuator/{id}
  • PATCH /json/actuationinterface/{id}
  • PATCH /json/aliasnamespace/{id}
  • PATCH /json/collection/{id}

Every endpoint on Swagger UI contains an exhaustive list of currently available patch operations.

Typical request body looks like this:

[
  {
    “op”: “replace”,
    “path”: “/popularName”,
    “value”: “New axiom name”
  },

  {
    “op”: “replace”,
    “path”: “/servedBy”,
    “value”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
  }
]

Forming patch operation request:

Every patch operation consists of three fields:

“op” – Operation type (add, replace, remove)
“path” – Patched property name (with / symbol before it)
“value” – Value to assign

Example:

  {
    “op”: “replace”,
    “path”: “/popularName”,
    “value”: “new Perfect Name”
  }

Choosing the operation type:

a.If the patched property is a list of values, then “add” operation should be chosen to add a new value to this list, and “remove” – to remove the specified value from the list. For example:

  {
    “op”: “add”,
    “path”: “/hasActuationInterfaces”,
    “value”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
  },
  {
    “op”: “remove”,
    “path”: “/hasActuationInterfaces”,
    “value”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
  }

b. If the patched property is a single value, “replace” operation should be used. For example:

  {
    “op”: “replace”,
    “path”: “/isMountedInBuildingComponent”,
    “value”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
  }

c If the patched property is a single value, but it is not mandatory and might be null, then either “replace” or “remove” operation can be used. For example:

  {
    “op”:”remove”,
    “path”:”/observesActuator”,
    “value”:”3fa85f64-5717-4562-b3fc-2c963f66afa6″
  },
  {
    “op”:”replace”,
    “path”:”/observesActuator”,
    “value”:”3fa85f64-5717-4562-b3fc-2c963f66afa6″
  }

Invalid or failed patch operations

A patch operation could

  • succeed and return “changed”:true
  • fail while returning “changed”:false
    (typically when the operation is structurally sound, but e.g. has an invalid RealEstateCore label for Quantity Kind or Placement Context)
  • fail while returning an error message
    (instead of returning an array of operations with “changed”:true and “changed”:false)

A request for multiple patch operations could partially fail (have some operations succeed while others fail). If one or more operations fail with an error message, then no patch operations will be applied. If one or more operations fail while returning “changed”:false but no error message, then the “changed”:true operations will go through.

Example response for partial failure resulting in an updated Super Device (but no change to the Quantity Kind):

  {
    “op”:”replace”,
    “path”:”/deviceQuantityKind”,
    “value”:”My Invalid Quantity Kind”,
    “changed”:false
  },
  {
    “op”:”replace”,
    “path”:”/hasSuperDevice”,
    “value”:”3fa85f64-5717-4562-b3fc-2c963f66afa6″,
    “changed”:true
 }

Properties that cannot be patched (yet)

Aliases can currently not be patched, alias patching will be added in future releases. To change, add or remove an alias, the whole object need to be updated using the PUT endpoint (from before).

Breaking changes

None

Fixes and minor updated

Minor performance improvements. Bug fixing.