# Reference.Delete Request

This message is used to delete an existing reference.

The Device API of the Ability platform allows a BL developer to create, read, update, and delete (CRUD) data for managing references from directly connected devices using the Device API. Specifically, the feature introduces support for the reference.delete message type initiated by a directly connected device.

# Idempotency

This request is idempotent, meaning that sending several identical requests will result in the reference being successfully deleted in IM. One of the two following outcomes will occur due to this design:

First delete of an existing reference will be successful
Following deletes of this reference will also be considered successful

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
objectId	Mandatory	Object definition identifier of the source object model.
model	Optional	Model definition identifier (modelId) of the source object model. If not provided, defaults to "abb.ability.device".
name	Mandatory	Name of the reference to be removed.

# Message Body

The body is composed of a well-formed JSON compliant to the .json schema.

Property	Mandatory	Description
to.objectId	Optional	Target object identifier. Must be in GUID format.
to.model	Optional	Target model definition identifier (modelId). Case sensitive. If not provided, defaults to "abb.ability.device".

{
"type": "object",
"properties": {
 "to": {
  "type": "object",
  "description": "target object model",
  "properties":,
  "objectId":"<objectId>",
   "type": "string",
   "format": "uuid",
  "model": "<model>",
    "type": "string",
    }
  }
}

# Message Format

{
  "properties": {
    "iothub-connection-device-id": "<authenticated device id>",
    "msgType": "action",
    "action": "reference.delete",
    "version": 2,
    "correlationId": "<correlation id>",
    "ack": "<ack>", 
    "target": "<connectivity path>",
    "timeout":"<integer>",
    "objectId": "<objectId>",
    "model": "<model>",
    "name": "<name of the reference to be removed>"
  },
  "body": {
    "to": {
      "objectId": "<target object model's objectId>",
      "model": "<target object model's model>"
    }
  }  
}

# Validation Rules

DCS validates all message properties, that the message body is in proper JSON format, and all message body properties as specified in the summary page of all v2 Device API messages.

# Functionality

# Description

If the target objectId is not provided in the request, remove all references outgoing from the source object model with the requested name.
If the target object model is provided in the request, remove a reference from the source object model and apply it to the target object model with the requested name.

NOTE

If there is no reference to delete, the request is considered successful.

A reference notification C2D message is not sent back.

NOTE

DCS will never send back a 'request-response' notification message. Any platform events generated by the IM service related to this request are ignored by the DCS.

If requested, an acknowledgement C2D message is sent back to the directly connected device where it can be propagated further, as needed (based on target). Note that the target is reused from the requested message. For more, see Acknowledgement Handling.

# Format of Returned Acknowledgement C2D Message

Successful acknowledgement:

{
    "properties": {
      "msgType": "ack",
      "action": "reference.delete",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ"
    },
    "body": {
      "success": true,
      "code": "ok",
      "details": ""
    }
}

Failed acknowledgement:

{
    "properties": {
      "msgType": "ack",
      "action": "reference.delete",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ"
    },
    "body": {
      "success": false,
      "code": "<error code>",
      "details": "<error detail>"
    }
}

← Reference.Create (V2) Owner.Remove (V2) →