recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Conduit API: Using Edit Endpoints
2@group conduit
3
4Describes how to use edit endpoints to create and update objects.
5
6Overview
7========
8
9Many applications provide `edit` endpoints, which are the primary way to
10create and update objects (like tasks) using the API.
11
12To create or edit an object, you'll build a list of //transactions// and pass
13them to the endpoint. Each transaction applies a change to a field or property
14on the object.
15
16For example, a transaction might change the title of an object or add
17subscribers.
18
19When creating an object, transactions will be applied to an empty object. When
20editing an object, transactions will be applied to an existing object.
21
22The best reference for a particular `edit` endpoint is the Conduit API console.
23For example, you can find the console page for `maniphest.edit` by navigating
24to {nav Conduit > maniphest.edit} in the web UI. This page contains detailed
25information about the endpoint and how it can be used.
26
27Creating Objects
28================
29
30To create objects, pass a list of transactions but leave `objectIdentifier`
31blank. This tells the endpoint that you want to create a new, empty object and
32then apply the transactions to it.
33
34
35Editing Objects
36===============
37
38To edit objects, pass a list of transactions and use `objectIdentifier` to
39specify which object to apply them to. You can normally pass an ID or PHID,
40and many applications also allow you to pass a monogram (for example, you can
41edit a task by passing `T123`).
42
43
44Building Transactions
45=====================
46
47When creating or editing objects, you'll build a list of transactions to
48apply. 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
67Applied to an empty object (say, a task), these transactions would create a new
68task with the specified title, description and subscribers.
69
70Applied to an existing object, they would retitle the task, change its
71description, and add new subscribers.
72
73The particular transactions available on each object are documented on the
74Conduit API console page for that object.
75
76
77Return Type
78===========
79
80WARNING: The structure of the return value from these methods is likely to
81change as ApplicationEditor evolves.
82
83Return 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
101The `object` key contains information about the object which was created or
102edited.
103
104The `transactions` key contains information about the transactions which were
105actually applied. For many reasons, the transactions which actually apply may
106be greater or fewer in number than the transactions you provided, or may differ
107in their nature in other ways.
108
109
110Next Steps
111==========
112
113Continue by:
114
115 - returning to the @{article:Conduit API Overview}.