src/docs/user/userguide/conduit_edit.diviner

   1 @title Conduit API: Using Edit Endpoints
   2 @group conduit
   3
   4 Describes how to use edit endpoints to create and update objects.
   5
   6 Overview
   7 ========
   8
   9 Many applications provide `edit` endpoints, which are the primary way to
  10 create and update objects (like tasks) using the API.
  11
  12 To create or edit an object, you'll build a list of //transactions// and pass
  13 them to the endpoint. Each transaction applies a change to a field or property
  14 on the object.
  15
  16 For example, a transaction might change the title of an object or add
  17 subscribers.
  18
  19 When creating an object, transactions will be applied to an empty object. When
  20 editing an object, transactions will be applied to an existing object.
  21
  22 The best reference for a particular `edit` endpoint is the Conduit API console.
  23 For example, you can find the console page for `maniphest.edit` by navigating
  24 to {nav Conduit > maniphest.edit} in the web UI. This page contains detailed
  25 information about the endpoint and how it can be used.
  26
  27 Creating Objects
  28 ================
  29
  30 To create objects, pass a list of transactions but leave `objectIdentfier`
  31 blank. This tells the endpoint that you want to create a new, empty object and
  32 then apply the transactions to it.
  33
  34
  35 Editing Objects
  36 ===============
  37
  38 To edit objects, pass a list of transactions and use `objectIdentifier` to
  39 specify which object to apply them to. You can normally pass an ID or PHID,
  40 and many applications also allow you to pass a monogram (for example, you can
  41 edit a task by passing `T123`).
  42
  43
  44 Building Transactions
  45 =====================
  46
  47 When creating or editing objects, you'll build a list of transactions to
  48 apply. This transaction list will look something like this:
  49
  50 ```lang=json, name="Example Transaction List"
  51 [
  52   {
  53     "type": "title",
  54     "value": "Assemble in the barnyard"
  55   },
  56   {
  57     "type": "description",
  58     "value": "All animals should assemble in the barnyard promptly."
  59   },
  60   {
  61     "type": "subscribers.add",
  62     "value": ["dog", "cat", "mouse"]
  63   }
  64 ]
  65 ```
  66
  67 Applied to an empty object (say, a task), these transactions would create a new
  68 task with the specified title, description and subscribers.
  69
  70 Applied to an existing object, they would retitle the task, change its
  71 description, and add new subscribers.
  72
  73 The particular transactions available on each object are documented on the
  74 Conduit API console page for that object.
  75
  76
  77 Return Type
  78 ===========
  79
  80 WARNING: The structure of the return value from these methods is likely to
  81 change as ApplicationEditor evolves.
  82
  83 Return values look something like this for now:
  84
  85 ```lang=json, name=Example Return Value
  86 {
  87   "object": {
  88     "phid": "PHID-XXXX-1111"
  89   },
  90   "transactions": [
  91     {
  92       "phid": "PHID-YYYY-1111",
  93     },
  94     {
  95       "phid": "PHID-YYYY-2222",
  96     }
  97   ]
  98 }
  99 ```
 100
 101 The `object` key contains information about the object which was created or
 102 edited.
 103
 104 The `transactions` key contains information about the transactions which were
 105 actually applied. For many reasons, the transactions which actually apply may
 106 be greater or fewer in number than the transactions you provided, or may differ
 107 in their nature in other ways.
 108
 109
 110 Next Steps
 111 ==========
 112
 113 Continue by:
 114
 115   - returning to the @{article:Conduit API Overview}.