|
1
|
# JSON API: /timeline |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Introduction](#intro) |
|
7
|
* [Branch Timeline](#branch) |
|
8
|
* [Technote (formerly Event) Timeline](#technote) |
|
9
|
* [Ticket Timeline](#ticket) |
|
10
|
* [Wiki Timeline](#wiki) |
|
11
|
|
|
12
|
--- |
|
13
|
|
|
14
|
<a id="intro"></a> |
|
15
|
# Introduction |
|
16
|
|
|
17
|
These requests return overview-level information about various types of |
|
18
|
changes. The response payload differs for each artifact type, and the |
|
19
|
current structures are almost certainly not "final" (e.g. we are still |
|
20
|
undecided on how/whether to handle artifact links within commit messages |
|
21
|
and whatnot). |
|
22
|
|
|
23
|
By default the entries are returned in chronological order from newest |
|
24
|
to oldest, but some options might change that. |
|
25
|
|
|
26
|
FIXME (20120623): we have some inconsistent `type` vs. `eventType` in |
|
27
|
the result sets. `type` is the current preferred choice (and it seems |
|
28
|
unlikely that `eventType` is actually used in any client code). We |
|
29
|
don't actually need either one (but a use for `type` is easily |
|
30
|
envisioned), and we may get rid of both. |
|
31
|
|
|
32
|
**Common request options (via CLI, GET or POST.payload):** |
|
33
|
|
|
34
|
- `limit=integer` limits the number of entries in the response. Default |
|
35
|
is unspecified (but is "quite possibly 20 or so"). A limit value of |
|
36
|
0 disables any limit, fetching all entries (which can take a really |
|
37
|
long time and might overload clients which have very limited |
|
38
|
memory).\ |
|
39
|
CLI mode: `--limit|-n #` |
|
40
|
- `after="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or |
|
41
|
after the given date string. Reverses the normal timeline sort |
|
42
|
order. Alias: "a". Only one of "after" or "before" can be used, and |
|
43
|
if both are specified then which one takes precedence is |
|
44
|
unspecified.\ |
|
45
|
CLI mode: `--after|-a "DATE[ TIME]"` |
|
46
|
- `before="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or |
|
47
|
before the given date string.\ |
|
48
|
CLI mode: `--before|-b "DATE[ TIME]" |
|
49
|
- TODOs, still to be ported from the HTML-mode timeline: |
|
50
|
- circa=DATETIME |
|
51
|
- tag=string |
|
52
|
- related=tag name |
|
53
|
- string=search string |
|
54
|
|
|
55
|
<a id="branch"></a> |
|
56
|
# Branch Timeline |
|
57
|
|
|
58
|
**Status:** partially implemented but undocumented because the utility |
|
59
|
of the current impl is under question. It also doesn't understand most |
|
60
|
of the common timeline options. |
|
61
|
|
|
62
|
<a id="checkin"></a> |
|
63
|
# Checkin Timeline |
|
64
|
|
|
65
|
**Status:** implemented 201109xx |
|
66
|
|
|
67
|
**Required privileges:** "o" |
|
68
|
|
|
69
|
**Request:** `/json/timeline/checkin` |
|
70
|
|
|
71
|
**Response payload example:** |
|
72
|
|
|
73
|
```json |
|
74
|
{ |
|
75
|
"limit": number, /* if not set, all records are returned */ |
|
76
|
"timeline":[{ |
|
77
|
"uuid":"be700e84336941ef1bcd08d676310b75b9070f43", |
|
78
|
"timestamp":1317094090, |
|
79
|
"comment":"Added /json/timeline/ci showFiles to ajax test page.", |
|
80
|
"user":"stephan", |
|
81
|
"isLeaf":true, |
|
82
|
"bgColor":null, /* not quite sure why this is null? */ |
|
83
|
"type":"ci", |
|
84
|
"parents": ["primary parent hash", "...other parent hashes"], |
|
85
|
"tags":["json"], |
|
86
|
"files":[{ |
|
87
|
"name":"ajax/index.html", |
|
88
|
"uuid":"9f00773a94cea6191dc3289aa24c0811b6d0d8fe", |
|
89
|
"parent":"50e337c33c27529e08a7037a8679fb84b976ad0b", |
|
90
|
"state":"modified" |
|
91
|
}] |
|
92
|
},...] |
|
93
|
} |
|
94
|
``` |
|
95
|
|
|
96
|
(Achtung: the `parents` property was called `prevUuid` prior to 20120316.) |
|
97
|
|
|
98
|
The `parents` property lists the checkins which were parents of this |
|
99
|
commit. The first entry in the array is the "primary parent" - the one |
|
100
|
which was not involved in a merge with the child. |
|
101
|
|
|
102
|
**Request options:** |
|
103
|
|
|
104
|
- `files=bool` toggles the addition of a "files" array property which |
|
105
|
contains objects describing the files changed by the commit, |
|
106
|
including their hash, previous hash, and state change type |
|
107
|
(modified, added, or removed). ([“uuid” here means hash][uvh])\ |
|
108
|
CLI mode: `--show-files|-f` |
|
109
|
- `tag|branch=string` selects only entries with the given tag or "close |
|
110
|
to" the given branch. Only one of these may be specified and if both |
|
111
|
are specified, which one takes precedence is unspecified. If the |
|
112
|
given tag/branch does not exist, an error response is generated. The |
|
113
|
difference between the two is subtle - tag filters only on the given |
|
114
|
tag (analog to the HTML interface's "r" option) whereas branch can |
|
115
|
also return entries from other branches which were merged into the |
|
116
|
requested branch (analog to the HTML interface's "b" option). If one |
|
117
|
of these is specified, the response payload will contain a "tag" |
|
118
|
*or* "branch" property with the tag/branch name given by the client. |
|
119
|
|
|
120
|
<a id="technote"></a> |
|
121
|
# Technote (formerly Event) Timeline |
|
122
|
|
|
123
|
**Status:** implemented 20180803 |
|
124
|
|
|
125
|
**Required privileges:** "j" |
|
126
|
|
|
127
|
**Request:** |
|
128
|
|
|
129
|
- `/json/timeline/technote` |
|
130
|
- DEPRECATED: `/json/timeline/event` (technotes were formerly called `events`) |
|
131
|
|
|
132
|
**Response payload example:** |
|
133
|
|
|
134
|
```json |
|
135
|
{ |
|
136
|
"limit": number, /* if not set, all records are returned */ |
|
137
|
"timeline":[{ |
|
138
|
"name":"8d18bf27e9f9ff8b9017edd55afc35701407d418", |
|
139
|
"uuid":"b23962c88c123924a77fd663e91af094780d920a", |
|
140
|
"timestamp":1478376113, |
|
141
|
"comment":"Style update due to [8d880f0bb4]", |
|
142
|
"user":"andygoth", |
|
143
|
"eventType":"e" |
|
144
|
},...] |
|
145
|
} |
|
146
|
``` |
|
147
|
|
|
148
|
The `uuid` of each entry can be passed to `/json/artifact` to fetch the raw |
|
149
|
event content. |
|
150
|
|
|
151
|
<a id="ticket"></a> |
|
152
|
# Ticket Timeline |
|
153
|
|
|
154
|
**Status:** implemented 201109xx |
|
155
|
|
|
156
|
**Required privileges:** "r" or "o" |
|
157
|
|
|
158
|
**Request:** `/json/timeline/ticket` |
|
159
|
|
|
160
|
**Response payload example:** |
|
161
|
|
|
162
|
```json |
|
163
|
{ |
|
164
|
"limit": number, /* if not set, all records are returned */ |
|
165
|
"timeline":[{ |
|
166
|
"uuid":"5065a5da060e181da49a618f8ae5dc245215e95b", |
|
167
|
"timestamp":1316511322, |
|
168
|
"user":"stephan", |
|
169
|
"eventType":"t", |
|
170
|
"comment":"Ticket [b64435dba9] <i>How to...</i>", |
|
171
|
"briefComment":"Ticket [b64435dba9]: 2 changes", |
|
172
|
"ticketUuid":"b64435dba9cceb709bd54fbc5883884d73f93491" |
|
173
|
},...] |
|
174
|
} |
|
175
|
``` |
|
176
|
|
|
177
|
**Notice that there are two [hashes][uvh] for tickets** - `uuid` is the change |
|
178
|
hash and `ticketUuid` is the actual ticket’s hash. This is an unfortunate |
|
179
|
discrepancy vis-a-vis the other timeline entries, which only have one |
|
180
|
hash. We may want to swap `uuid` to mean the ticket hash and change `uuid` |
|
181
|
to `commitHash`. |
|
182
|
|
|
183
|
<a id="wiki"></a> |
|
184
|
# Wiki Timeline |
|
185
|
|
|
186
|
**Status:** implemented 201109xx |
|
187
|
|
|
188
|
**Required privileges:** "j" or "o" |
|
189
|
|
|
190
|
**Requests:** |
|
191
|
|
|
192
|
- `/json/timeline/wiki` |
|
193
|
- `/json/wiki/timeline` (alias) |
|
194
|
|
|
195
|
**Response payload example:** |
|
196
|
|
|
197
|
```json |
|
198
|
{ |
|
199
|
"limit": number, /* if not set, all records are returned */ |
|
200
|
"timeline":[{ |
|
201
|
"uuid":"4b2026f06eb48eaf187209fcb05ba5438c3b0ef0", |
|
202
|
"timestamp":1331351121, |
|
203
|
"comment":"Changes to wiki page [Page3]", |
|
204
|
"user":"stephan", |
|
205
|
"eventType":"w" |
|
206
|
},...] |
|
207
|
} |
|
208
|
``` |
|
209
|
|
|
210
|
The `uuid` of each entry can be passed to `/json/artifact` or |
|
211
|
`/json/wiki/get?uuid=...` to fetch the raw page and the hash of the |
|
212
|
parent version. |
|
213
|
|
|
214
|
[uvh]: ../hashes.md#uvh |
|
215
|
|