@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
Continue hammering new *.search / *.edit documentation into shape
Summary: Ref T9964. Create some docuemntation for this stuff, and clean up the *.edit endpoints a bit.
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T9964
Differential Revision: https://secure.phabricator.com/D14798
+358
-157
+2
-2
src/applications/conduit/application/PhabricatorConduitApplication.php
+2
-2
src/applications/conduit/application/PhabricatorConduitApplication.php
···
17
17
public function getHelpDocumentationArticles(PhabricatorUser $viewer) {
18
18
return array(
19
19
array(
20
-
'name' => pht('Conduit Technical Documentation'),
21
-
'href' => PhabricatorEnv::getDoclink('Conduit Technical Documentation'),
20
+
'name' => pht('Conduit API Overview'),
21
+
'href' => PhabricatorEnv::getDoclink('Conduit API Overview'),
22
22
),
23
23
);
24
24
}
+3
-1
src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
+3
-1
src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
···
42
42
final public function getMethodDescription() {
43
43
return pht(
44
44
'This is a standard **ApplicationSearch** method which will let you '.
45
-
'list, query, or search for objects.');
45
+
'list, query, or search for objects. For documentation on these '.
46
+
'endpoints, see **[[ %s | Conduit API: Using Search Endpoints ]]**.',
47
+
PhabricatorEnv::getDoclink('Conduit API: Using Edit Endpoints'));
46
48
}
47
49
48
50
final public function getMethodDocumentation() {
+85
-126
src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
+85
-126
src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
···
38
38
}
39
39
40
40
final public function getMethodDescription() {
41
+
return pht(
42
+
'This is a standard **ApplicationEditor** method which allows you to '.
43
+
'create and modify objects by applying transactions. For documentation '.
44
+
'on these endpoints, see '.
45
+
'**[[ %s | Conduit API: Using Edit Endpoints ]]**.',
46
+
PhabricatorEnv::getDoclink('Conduit API: Using Edit Endpoints'));
47
+
}
48
+
49
+
final public function getMethodDocumentation() {
41
50
$viewer = $this->getViewer();
42
51
43
52
$engine = $this->newEditEngine()
···
47
56
48
57
$out = array();
49
58
50
-
$out[] = pht(<<<EOTEXT
51
-
This is a standard **ApplicationEditor** method which allows you to create and
52
-
modify objects by applying transactions.
59
+
$out[] = $this->buildEditTypesBoxes($engine, $types);
53
60
54
-
Each transaction applies one change to the object. For example, to create an
55
-
object with a specific title or change the title of an existing object you might
56
-
start by building a transaction like this:
57
-
58
-
```lang=json, name=Example Single Transaction
59
-
{
60
-
"type": "title",
61
-
"value": "New Object Title"
62
-
}
63
-
```
64
-
65
-
By passing a list of transactions in the `transactions` parameter, you can
66
-
apply a sequence of edits. For example, you'll often pass a value like this to
67
-
create an object with several field values or apply changes to multiple fields:
68
-
69
-
```lang=json, name=Example Transaction List
70
-
[
71
-
{
72
-
"type": "title",
73
-
"value": "New Object Title"
74
-
},
75
-
{
76
-
"type": "body",
77
-
"value": "New body text for the object."
78
-
},
79
-
{
80
-
"type": "projects.add",
81
-
"value": ["PHID-PROJ-1111", "PHID-PROJ-2222"]
61
+
return $out;
82
62
}
83
-
]
84
-
```
85
63
86
-
Exactly which types of edits are available depends on the object you're editing.
64
+
private function buildEditTypesBoxes(
65
+
PhabricatorEditEngine $engine,
66
+
array $types) {
87
67
68
+
$boxes = array();
88
69
89
-
Creating Objects
90
-
----------------
70
+
$summary_info = pht(
71
+
'This endpoint supports these types of transactions. See below for '.
72
+
'detailed information about each transaction type.');
91
73
92
-
To create an object, pass a list of `transactions` but leave `objectIdentifier`
93
-
empty. This will create a new object with the initial field values you
94
-
specify.
74
+
$rows = array();
75
+
foreach ($types as $type) {
76
+
$rows[] = array(
77
+
$type->getEditType(),
78
+
$type->getConduitDescription(),
79
+
);
80
+
}
95
81
82
+
$summary_table = id(new AphrontTableView($rows))
83
+
->setHeaders(
84
+
array(
85
+
pht('Key'),
86
+
pht('Description'),
87
+
))
88
+
->setColumnClasses(
89
+
array(
90
+
'prewrap',
91
+
'wide',
92
+
));
96
93
97
-
Editing Objects
98
-
---------------
94
+
$boxes[] = id(new PHUIObjectBoxView())
95
+
->setHeaderText(pht('Transaction Types'))
96
+
->setCollapsed(true)
97
+
->appendChild($this->buildRemarkup($summary_info))
98
+
->appendChild($summary_table);
99
99
100
-
To edit an object, pass a list of `transactions` and specify an object to
101
-
apply them to with `objectIdentifier`. This will apply the changes to the
102
-
object.
100
+
foreach ($types as $type) {
101
+
$section = array();
103
102
104
-
You may pass an ID (like `123`), PHID (like `PHID-WXYZ-abcdef...`), or
105
-
monogram (like `T123`, for objects which have monograms).
103
+
$section[] = $type->getConduitDescription();
106
104
105
+
$type_documentation = $type->getConduitDocumentation();
106
+
if (strlen($type_documentation)) {
107
+
$section[] = $type_documentation;
108
+
}
107
109
108
-
Return Type
109
-
-----------
110
+
$section = implode("\n\n", $section);
110
111
111
-
WARNING: The structure of the return value from these methods is likely to
112
-
change as ApplicationEditor evolves.
112
+
$rows = array();
113
113
114
-
Return values look something like this for now:
114
+
$rows[] = array(
115
+
'type',
116
+
'const',
117
+
$type->getEditType(),
118
+
);
115
119
116
-
```lang=json, name=Example Return Value
117
-
{
118
-
"object": {
119
-
"phid": "PHID-XXXX-1111"
120
-
},
121
-
"transactions": [
122
-
{
123
-
"phid": "PHID-YYYY-1111",
124
-
},
125
-
{
126
-
"phid": "PHID-YYYY-2222",
127
-
}
128
-
]
129
-
}
130
-
```
131
-
132
-
The `object` key contains information about the object which was created or
133
-
edited.
134
-
135
-
The `transactions` key contains information about the transactions which were
136
-
actually applied. For many reasons, the transactions which actually apply may
137
-
be greater or fewer in number than the transactions you provided, or may differ
138
-
in their nature in other ways.
139
-
140
-
141
-
Edit Types
142
-
==========
143
-
144
-
This API method supports these edit types:
145
-
EOTEXT
120
+
$rows[] = array(
121
+
'value',
122
+
$type->getConduitType(),
123
+
$type->getConduitTypeDescription(),
146
124
);
147
125
148
-
$key = pht('Key');
149
-
$description = pht('Description');
150
-
$head_type = pht('Type');
126
+
$type_table = id(new AphrontTableView($rows))
127
+
->setHeaders(
128
+
array(
129
+
pht('Key'),
130
+
pht('Type'),
131
+
pht('Description'),
132
+
))
133
+
->setColumnClasses(
134
+
array(
135
+
'prewrap',
136
+
'prewrap',
137
+
'wide',
138
+
));
151
139
152
-
$table = array();
153
-
$table[] = "| {$key} | {$description} |";
154
-
$table[] = '|--------|----------------|';
155
-
foreach ($types as $type) {
156
-
$edit_type = $type->getEditType();
157
-
$edit_description = $type->getConduitDescription();
158
-
$table[] = "| `{$edit_type}` | {$edit_description} |";
140
+
$boxes[] = id(new PHUIObjectBoxView())
141
+
->setHeaderText(pht('Transaction Type: %s', $type->getEditType()))
142
+
->setCollapsed(true)
143
+
->appendChild($this->buildRemarkup($section))
144
+
->appendChild($type_table);
159
145
}
160
146
161
-
$out[] = implode("\n", $table);
162
-
163
-
foreach ($types as $type) {
164
-
$section = array();
165
-
$section[] = pht('Edit Type: %s', $type->getEditType());
166
-
$section[] = '---------';
167
-
$section[] = null;
168
-
$section[] = $type->getConduitDescription();
169
-
$section[] = null;
170
-
$section[] = pht(
171
-
'This edit generates transactions of type `%s` internally.',
172
-
$type->getTransactionType());
173
-
$section[] = null;
174
-
175
-
$type_documentation = $type->getConduitDocumentation();
176
-
if ($type_documentation) {
177
-
$section[] = $type_documentation;
178
-
$section[] = null;
179
-
}
147
+
return $boxes;
148
+
}
180
149
181
-
$type_description = pht(
182
-
'Use `%s` to select this edit type.',
183
-
$type->getEditType());
184
150
185
-
$value_type = $type->getConduitType();
186
-
$value_description = $type->getConduitTypeDescription();
187
-
188
-
$table = array();
189
-
$table[] = "| {$key} | {$head_type} | {$description} |";
190
-
$table[] = '|--------|--------------|----------------|';
191
-
$table[] = "| `type` | `const` | {$type_description} |";
192
-
$table[] = "| `value` | `{$value_type}` | {$value_description} |";
193
-
$section[] = implode("\n", $table);
151
+
private function buildRemarkup($remarkup) {
152
+
$viewer = $this->getViewer();
194
153
195
-
$out[] = implode("\n", $section);
196
-
}
154
+
$view = new PHUIRemarkupView($viewer, $remarkup);
197
155
198
-
$out = implode("\n\n", $out);
199
-
return $out;
156
+
return id(new PHUIBoxView())
157
+
->appendChild($view)
158
+
->addPadding(PHUI::PADDING_LARGE);
200
159
}
201
160
202
161
}
+3
src/docs/book/user.book
+3
src/docs/book/user.book
-28
src/docs/tech/conduit.diviner
-28
src/docs/tech/conduit.diviner
···
1
-
@title Conduit Technical Documentation
2
-
@group conduit
3
-
4
-
Technical overview of the Conduit API.
5
-
6
-
Overview
7
-
========
8
-
9
-
Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
10
-
pass a JSON blob, and usually get a JSON blob back, although both call and
11
-
result formats are flexible in some cases.
12
-
13
-
The easiest way to begin exploring Conduit is by visiting {nav Conduit} in the
14
-
web UI. The application provides an API console which you can use to explore
15
-
available methods, make calls, read documentation, and see examples.
16
-
17
-
The API console has details about how to construct calls and generate API
18
-
tokens for authentication.
19
-
20
-
The three primary ways to make Conduit calls are:
21
-
22
-
- `arc call-conduit`: You can use this `arc` command to execute low-level
23
-
Conduit calls.
24
-
- `curl`: You can format a call with basic HTTP parameters and cURL.
25
-
- `ConduitClient`:
26
-
27
-
There are also clients available in other languages. The Arcanist CLI client
28
-
for Phabricator is implemented over Conduit.
+8
src/docs/user/field/conduit_changes.diviner
+8
src/docs/user/field/conduit_changes.diviner
···
49
49
to identify callers and notify them to upgrade or switch away. When the
50
50
changelogs mention a method removal, you can use the call logs to verify that
51
51
you will not be impacted.
52
+
53
+
54
+
Next Steps
55
+
==========
56
+
57
+
Continue by:
58
+
59
+
- returning to @{article:Conduit API Overview}.
+68
src/docs/user/userguide/conduit.diviner
+68
src/docs/user/userguide/conduit.diviner
···
1
+
@title Conduit API Overview
2
+
@group conduit
3
+
4
+
Overview of the Conduit API.
5
+
6
+
Overview
7
+
========
8
+
9
+
Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
10
+
pass a JSON blob, and usually get a JSON blob back, although both call and
11
+
result formats are flexible in some cases.
12
+
13
+
API Clients
14
+
===========
15
+
16
+
The primary ways to make Conduit calls are:
17
+
18
+
**Web Console**: The {nav Conduit} application provides a web UI for exploring
19
+
the API and making calls. This is the best starting point for learning about
20
+
the API. See the next section for details.
21
+
22
+
`ConduitClient`: This is the official client available in `libphutil`, and
23
+
the one used by `arc`.
24
+
25
+
`arc call-conduit`: You can use this `arc` command to execute low-level
26
+
Conduit calls by piping JSON in to stdin. This can provide a simple way
27
+
to explore the API, or a quick way to get API access from a script written
28
+
in another language without needing a real client.
29
+
30
+
`curl`: You can format a call with basic HTTP parameters and cURL. The console
31
+
includes examples which show how to format calls.
32
+
33
+
**Other Clients**: There are also clients available in other languages. You
34
+
can check the [[ https://secure.phabricator.com/w/community_resources/ |
35
+
Community Resources ]] page for links.
36
+
37
+
API Console
38
+
===========
39
+
40
+
The easiest way to begin exploring Conduit is by visiting {nav Conduit} in the
41
+
web UI. The application provides an API console which you can use to explore
42
+
available methods, make calls, read documentation, and see examples.
43
+
44
+
The API console has details about how to construct calls and generate API
45
+
tokens for authentication.
46
+
47
+
48
+
Querying and Reading Objects
49
+
============================
50
+
51
+
For information on searching for objects and reading their properties and
52
+
information, see @{article:Conduit API: Using Search Endpoints}.
53
+
54
+
55
+
Creating and Editing Objects
56
+
============================
57
+
58
+
For information on creating, editing and updating objects, see
59
+
@{article:Conduit API: Using Search Endpoints}.
60
+
61
+
62
+
Next Steps
63
+
==========
64
+
65
+
Continue by:
66
+
67
+
- reading recommendations on responding to API changes in
68
+
@{article:Managing Conduit Changes}.
+115
src/docs/user/userguide/conduit_edit.diviner
+115
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 applicaitons 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}.
+74
src/docs/user/userguide/conduit_search.diviner
+74
src/docs/user/userguide/conduit_search.diviner
···
1
+
@title Conduit API: Using Search Endpoints
2
+
@group conduit
3
+
4
+
Describes how to use search endpoints to find objects and read information.
5
+
6
+
Overview
7
+
========
8
+
9
+
Many applications provide `search` endpoints, which are the primary way to
10
+
get information about objects (like tasks) using the API.
11
+
12
+
To read information about objects, you'll specify a //query// which describes
13
+
which objects you want to retrieve. You can query for specific objects by
14
+
ID, or for a list of objects satisfying certain constraints (for example, open
15
+
tasks in a particular project).
16
+
17
+
The best reference for a particular `search` endpoint is the Conduit API
18
+
console. For example, you can find the console page for `maniphest.search` by
19
+
navigating to {nav Conduit > maniphest.search} in the web UI. This page
20
+
contains detailed information about the endpoint and how it can be used.
21
+
22
+
23
+
Specifying a Query
24
+
==================
25
+
26
+
The simplest query you can use is no query at all: just make a request with
27
+
no parameters. This will return the first page of visible objects. Most
28
+
applications sort objects by creation date by default, so usually this is
29
+
the 100 most recent objects.
30
+
31
+
The easiest way to constrain results is to use a builtin query or a custom
32
+
query that you build using the web UI. To do this, first issue the query in
33
+
the web UI (for example, by clicking the builtin link on the left nav of the
34
+
list view, or by submitting the query form).
35
+
36
+
The results page will include a //query key// in the URL. For builtin queries,
37
+
this is usually a human-readable term like `all` or `active`. For custom
38
+
queries, it is a hash value which looks something like `MT0Rh0fB2x4I`.
39
+
40
+
You can submit this key in the `queryKey` parameter to issue the exact same
41
+
query via the Conduit API. This provides a simple way to build complex queries:
42
+
just build the via the web UI, then reuse the same query in the API.
43
+
44
+
If you need more control or want to build dynamic queries, use the
45
+
`constraints` parameter to set constraints for individual query fields.
46
+
47
+
For more details, consult the Conduit API console documentation for the
48
+
method you're using. It includes documentation on all available constraints
49
+
and lists builtin and saved query keys.
50
+
51
+
52
+
Attachments
53
+
===========
54
+
55
+
By default, queries return basic information about objects. If you want more
56
+
detailed information, most applications offer //attachments// which can let
57
+
you retrieve more information.
58
+
59
+
For example, subscribers and projects are not returned by default, but you
60
+
can use subscribers to query them if you need this data.
61
+
62
+
Asking for more data means a slower query and a larger result, so usually you
63
+
should only ask for data you need.
64
+
65
+
The Conduit API console page for each query method has detailed information
66
+
on which attachments it supports.
67
+
68
+
69
+
Next Steps
70
+
==========
71
+
72
+
Continue by:
73
+
74
+
- returning to the @{article:Conduit API Overview}.