Writing Data to the Ledger

POST /:ledgerId/v1/create

(This endpoint is a replacement of deprecated endpoint: POST /:ledgerId/command/create)

Parameter Description
templateId TemplateId JsObject containing moduleName and entityName
payload JsObject containing list of key-value pairs defined in the target template's fields

request for Create:

POST /data/:ledgerId/v1/create HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
  "templateId": "Iou:Iou",
  "payload": {
    "observers": [],
    "issuer": "rztds0vfs6hgd1np",
    "amount": "999.99",
    "currency": "USD",
    "owner": "rztds0vfs6hgd1np"
  }
}

HTTP Success response

{
    "result": {
        "agreementText": "",
        "contractId": "#474:0",
        "observers": [],
        "payload": {
            "observers": [],
            "issuer": "rztds0vfs6hgd1np",
            "amount": "999.99",
            "currency": "USD",
            "owner": "rztds0vfs6hgd1np"
        },
        "signatories": [
            "rztds0vfs6hgd1np"
        ],
        "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:Iou"
    },
    "status": 200
}

HTTP Error response

{
    "status": 400,
    "errors": [
        "JsonError: lookupLfIdentifier: PackageService input error: Cannot resolve templateId: TemplateId(None,Iou,Iou_Foo)"
    ]
}

POST /:ledgerId/v1/exercise

(This endpoint is a replacement of deprecated endpoint: POST /:ledgerId/command/exercise)

Parameter Description
templateId TemplateId JsObject containing moduleName and entityName
contractId contractId of the target contract
choice Name of the choice to exercise
argument JsObject containing list of key-value pairs to the choice. if the choice does not accept any arguments then an empty object must be used.

request for exercise by contractId:

POST /data/:ledgerId/v1/exercise HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "templateId": "Iou:Iou",
    "contractId": "#474:0",
    "choice": "Iou_Transfer",
    "argument": {
        "newOwner": "Alice"
    }
}

HTTP Success Response

{
    "result": {
        "events": [
            {
                "archived": {
                    "contractId": "#474:0",
                    "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:Iou"
                }
            },
            {
                "created": {
                    "agreementText": "",
                    "contractId": "#475:1",
                    "observers": [
                        "kx8tm3t10cxlapn5"
                    ],
                    "payload": {
                        "iou": {
                            "observers": [],
                            "issuer": "rztds0vfs6hgd1np",
                            "amount": "999.99",
                            "currency": "USD",
                            "owner": "rztds0vfs6hgd1np"
                        },
                        "newOwner": "kx8tm3t10cxlapn5"
                    },
                    "signatories": [
                        "rztds0vfs6hgd1np"
                    ],
                    "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:IouTransfer"
                }
            }
        ],
        "exerciseResult": "#475:1"
    },
    "status": 200
}

HTTP Error Response

{
    "status": 500,
    "errors": [
        "INVALID_ARGUMENT: Command interpretation error in LF-DAMLe: dependency error: couldn't find contract AbsoluteContractId(#21:0). Details: N/A."
    ]
}

Request for exercise by Contract Key:

POST /data/:ledgerId/command/exercise HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "templateId": "Account:Account",
    "key": ["Alice", "abc123"],
    "choice": "Archive",
    "argument": {}
}

HTTP Success Response

{
    "status": 200,
    "result": {
        "exerciseResult": "#201:1",
        "events": [
            {
                "archived": {
                    "contractId": "#124:0",
                    "templateId": "11c8f3ace75868d28136adc5cfc1de265a9ee5ad73fe8f2db97510e3631096a2:Iou:Iou"
                }
            },
            {
                "created": {
                    "observers": [],
                    "agreementText": "",
                    "payload": {
                        "iou": {
                            "observers": [],
                            "issuer": "Alice",
                            "amount": "999.99",
                            "currency": "USD",
                            "owner": "Alice"
                        },
                        "newOwner": "Alice"
                    },
                    "signatories": [
                        "Alice"
                    ],
                    "contractId": "#201:1",
                    "templateId": "11c8f3ace75868d28136adc5cfc1de265a9ee5ad73fe8f2db97510e3631096a2:Iou:IouTransfer"
                }
            }
        ]
    }
}

POST /:ledgerId/v1/create-and-exercise

Parameter Description
templateId TemplateId JsObject containing moduleName and entityName
payload JsObject containing list of key-value pairs defined in the target template's fields
choice Name of the choice to exercise
argument JsObject containing list of key-value pairs to the choice. if the choice does not accept any arguments then an empty object must be used.

HTTP POST request for Create:

POST /data/:ledgerId/create-and-exercise HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application.json
{
  "templateId": "Iou:Iou",
  "payload": {
    "observers": [],
    "issuer": "dz1ys3yl4g41e1m2",
    "amount": "999.99",
    "currency": "USD",
    "owner": "dz1ys3yl4g41e1m2"
  },
  "choice": "Iou_Transfer",
  "argument": {
    "newOwner": "lopiw5orw840lr01"
  }
}

Http Success Response

{
    "result": {
        "events": [
            {
                "created": {
                    "agreementText": "",
                    "contractId": "#190:0",
                    "observers": [],
                    "payload": {
                        "observers": [],
                        "issuer": "dz1ys3yl4g41e1m2",
                        "amount": "999.99",
                        "currency": "USD",
                        "owner": "dz1ys3yl4g41e1m2"
                    },
                    "signatories": [
                        "dz1ys3yl4g41e1m2"
                    ],
                    "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:Iou"
                }
            },
            {
                "archived": {
                    "contractId": "#190:0",
                    "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:Iou"
                }
            },
            {
                "created": {
                    "agreementText": "",
                    "contractId": "#190:2",
                    "observers": [
                        "lopiw5orw840lr01"
                    ],
                    "payload": {
                        "iou": {
                            "observers": [],
                            "issuer": "dz1ys3yl4g41e1m2",
                            "amount": "999.99",
                            "currency": "USD",
                            "owner": "dz1ys3yl4g41e1m2"
                        },
                        "newOwner": "lopiw5orw840lr01"
                    },
                    "signatories": [
                        "dz1ys3yl4g41e1m2"
                    ],
                    "templateId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f:Iou:IouTransfer"
                }
            }
        ],
        "exerciseResult": "#190:2"
    },
    "status": 200
}

(deprecated) POST /:ledgerId/command

Issues a set of create or exercise commands
(We will keep this endpoint until DAML SDK's json-api become stable)

Parameter Description
workflowId Identifier of the on-ledger workflow that this command is part of
commandId A unique number for each new command within an application domain
commands A list of Create or Exercise Command jsObjects

HTTP POST request for Create:

POST /data/:ledgerId/command HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "workflowId": "82c10e81-35cc-416a-a63d-fe6a89982bc3",
    "commandId": "56e0410d-f27c-40d8-b43b-d6eb7a6318c1",
    "commands": [
        {
            "createArguments": {
                "observers": ["eg024sej3vhty549"],
                "issuer": "eg024sej3vhty549",
                "owner": "eg024sej3vhty549",
                "currency": "USD",
                "amount": "100"
            },
            "templateId": "Iou.Iou"
        }
    ]
}

HTTP Success response

{
    "commandId": "56e0410d-f27c-40d8-b43b-d6eb7a6318c1",
    "result": [
        {
            "created": {
                "agreementText": "",
                "arguments": {
                    "observers": [
                        "eg024sej3vhty549"
                    ],
                    "issuer": "eg024sej3vhty549",
                    "amount": "100.0",
                    "currency": "USD",
                    "owner": "eg024sej3vhty549"
                },
                "contractId": "#38:0",
                "observers": [
                    []
                ],
                "signatories": [
                    "eg024sej3vhty549"
                ],
                "templateId": {
                    "entityName": "IouTransfer",
                    "moduleName": "Iou",
                    "packageId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f"
                },
                "witnessParties": [
                    "eg024sej3vhty549"
                ]
            }
        }
    ],
    "status": 200,
    "description": null,
    "success": true
}

HTTP POST request for Exercise:

POST /data/:ledgerId/command HTTP/1.1
Host: api.projectdabl.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
  "workflowId": "18d98090-41be-425a-8f65-e4fff9db19fb",
  "commandId": "5b149ed6-8adc-49a6-82ef-2c11f9cfc2a4",
  "commands": [
    {
      "contractId": "#18:0",
      "choice": "Iou_Transfer",
      "templateId": "Iou:Iou",
      "choiceArgument": {
        "newOwner": "uwl0en23smc6fwwo"
      }
    }
  ]
}

HTTP Success Response:

{
  "success": true,
  "description": null,
  "result": [
    {
      "archived": {
        "contractId": "#18:1",
        "templateId": {
          "packageId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f",
          "moduleName": "Iou",
          "entityName": "Iou"
        },
        "witnessParties": [
          "wk88uml0v31xz9hu"
        ]
      }
    },
    {
      "created": {
        "observers": [
          []
        ],
        "agreementText": "",
        "signatories": [
          "wk88uml0v31xz9hu",
          "uwl0en23smc6fwwo"
        ],
        "contractId": "#27:1",
        "templateId": {
          "packageId": "ec4ff7a9c2adb530faf269fac0678b700aa0f99faa7624f3fdb97536b544830f",
          "moduleName": "Iou",
          "entityName": "IouTransfer"
        },
        "witnessParties": [
          "wk88uml0v31xz9hu"
        ],
        "argument": {
          "iou": {
            "observers": [],
            "issuer": "uwl0en23smc6fwwo",
            "amount": "999.99",
            "currency": "GBP",
            "owner": "wk88uml0v31xz9hu"
          },
          "newOwner": "uwl0en23smc6fwwo"
        }
      }
    }
  ],
  "status": 200,
  "commandId": "051e41dc-2e43-4d8a-9e57-2042ce0b6fc7"
}

HTTP Error response

{
    "success": false,
    "status": 400,
    "description": "Cannot parse request body as JSON command: Template named IouTrade.IouTrade does nothave choice TradeProposal_Foo",
    "result": []
}