From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/json-api/api-timeline.md | 214 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 www/json-api/api-timeline.md (limited to 'www/json-api/api-timeline.md') diff --git a/www/json-api/api-timeline.md b/www/json-api/api-timeline.md new file mode 100644 index 0000000..b0ff196 --- /dev/null +++ b/www/json-api/api-timeline.md @@ -0,0 +1,214 @@ +# JSON API: /timeline +([⬑JSON API Index](index.md)) + +Jump to: + +* [Introduction](#intro) +* [Branch Timeline](#branch) +* [Technote (formerly Event) Timeline](#technote) +* [Ticket Timeline](#ticket) +* [Wiki Timeline](#wiki) + +--- + + +# Introduction + +These requests return overview-level information about various types of +changes. The response payload differs for each artifact type, and the +current structures are almost certainly not "final" (e.g. we are still +undecided on how/whether to handle artifact links within commit messages +and whatnot). + +By default the entries are returned in chronological order from newest +to oldest, but some options might change that. + +FIXME (20120623): we have some inconsistent `type` vs. `eventType` in +the result sets. `type` is the current preferred choice (and it seems +unlikely that `eventType` is actually used in any client code). We +don't actually need either one (but a use for `type` is easily +envisioned), and we may get rid of both. + +**Common request options (via CLI, GET or POST.payload):** + +- `limit=integer` limits the number of entries in the response. Default + is unspecified (but is "quite possibly 20 or so"). A limit value of + 0 disables any limit, fetching all entries (which can take a really + long time and might overload clients which have very limited + memory).\ + CLI mode: `--limit|-n #` +- `after="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or + after the given date string. Reverses the normal timeline sort + order. Alias: "a". Only one of "after" or "before" can be used, and + if both are specified then which one takes precedence is + unspecified.\ + CLI mode: `--after|-a "DATE[ TIME]"` +- `before="YYYY-MM-DD[ HH:mm:ss]"` limits the search to items on or + before the given date string.\ + CLI mode: `--before|-b "DATE[ TIME]" +- TODOs, still to be ported from the HTML-mode timeline: + - circa=DATETIME + - tag=string + - related=tag name + - string=search string + + +# Branch Timeline + +**Status:** partially implemented but undocumented because the utility +of the current impl is under question. It also doesn't understand most +of the common timeline options. + + +# Checkin Timeline + +**Status:** implemented 201109xx + +**Required privileges:** "o" + +**Request:** `/json/timeline/checkin` + +**Response payload example:** + +```json +{ +"limit": number, /* if not set, all records are returned */ +"timeline":[{ + "uuid":"be700e84336941ef1bcd08d676310b75b9070f43", + "timestamp":1317094090, + "comment":"Added /json/timeline/ci showFiles to ajax test page.", + "user":"stephan", + "isLeaf":true, + "bgColor":null, /* not quite sure why this is null? */ + "type":"ci", + "parents": ["primary parent hash", "...other parent hashes"], + "tags":["json"], + "files":[{ + "name":"ajax/index.html", + "uuid":"9f00773a94cea6191dc3289aa24c0811b6d0d8fe", + "parent":"50e337c33c27529e08a7037a8679fb84b976ad0b", + "state":"modified" + }] + },...] +} +``` + +(Achtung: the `parents` property was called `prevUuid` prior to 20120316.) + +The `parents` property lists the checkins which were parents of this +commit. The first entry in the array is the "primary parent" - the one +which was not involved in a merge with the child. + +**Request options:** + +- `files=bool` toggles the addition of a "files" array property which + contains objects describing the files changed by the commit, + including their hash, previous hash, and state change type + (modified, added, or removed). ([“uuid” here means hash][uvh])\ + CLI mode: `--show-files|-f` +- `tag|branch=string` selects only entries with the given tag or "close + to" the given branch. Only one of these may be specified and if both + are specified, which one takes precedence is unspecified. If the + given tag/branch does not exist, an error response is generated. The + difference between the two is subtle - tag filters only on the given + tag (analog to the HTML interface's "r" option) whereas branch can + also return entries from other branches which were merged into the + requested branch (analog to the HTML interface's "b" option). If one + of these is specified, the response payload will contain a "tag" + *or* "branch" property with the tag/branch name given by the client. + + +# Technote (formerly Event) Timeline + +**Status:** implemented 20180803 + +**Required privileges:** "j" + +**Request:** + +- `/json/timeline/technote` +- DEPRECATED: `/json/timeline/event` (technotes were formerly called `events`) + +**Response payload example:** + +```json +{ +"limit": number, /* if not set, all records are returned */ +"timeline":[{ + "name":"8d18bf27e9f9ff8b9017edd55afc35701407d418", + "uuid":"b23962c88c123924a77fd663e91af094780d920a", + "timestamp":1478376113, + "comment":"Style update due to [8d880f0bb4]", + "user":"andygoth", + "eventType":"e" + },...] +} +``` + +The `uuid` of each entry can be passed to `/json/artifact` to fetch the raw +event content. + + +# Ticket Timeline + +**Status:** implemented 201109xx + +**Required privileges:** "r" or "o" + +**Request:** `/json/timeline/ticket` + +**Response payload example:** + +```json +{ + "limit": number, /* if not set, all records are returned */ + "timeline":[{ + "uuid":"5065a5da060e181da49a618f8ae5dc245215e95b", + "timestamp":1316511322, + "user":"stephan", + "eventType":"t", + "comment":"Ticket [b64435dba9] <i>How to...</i>", + "briefComment":"Ticket [b64435dba9]: 2 changes", + "ticketUuid":"b64435dba9cceb709bd54fbc5883884d73f93491" + },...] +} +``` + +**Notice that there are two [hashes][uvh] for tickets** - `uuid` is the change +hash and `ticketUuid` is the actual ticket’s hash. This is an unfortunate +discrepancy vis-a-vis the other timeline entries, which only have one +hash. We may want to swap `uuid` to mean the ticket hash and change `uuid` +to `commitHash`. + + +# Wiki Timeline + +**Status:** implemented 201109xx + +**Required privileges:** "j" or "o" + +**Requests:** + +- `/json/timeline/wiki` +- `/json/wiki/timeline` (alias) + +**Response payload example:** + +```json +{ +"limit": number, /* if not set, all records are returned */ +"timeline":[{ + "uuid":"4b2026f06eb48eaf187209fcb05ba5438c3b0ef0", + "timestamp":1331351121, + "comment":"Changes to wiki page [Page3]", + "user":"stephan", + "eventType":"w" + },...] +} +``` + +The `uuid` of each entry can be passed to `/json/artifact` or +`/json/wiki/get?uuid=...` to fetch the raw page and the hash of the +parent version. + +[uvh]: ../hashes.md#uvh -- cgit v1.3.1