diff options
Diffstat (limited to 'www/json-api/api-tag.md')
| -rw-r--r-- | www/json-api/api-tag.md | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/www/json-api/api-tag.md b/www/json-api/api-tag.md new file mode 100644 index 0000000..a9faede --- /dev/null +++ b/www/json-api/api-tag.md @@ -0,0 +1,229 @@ +# JSON API: /tag +([⬑JSON API Index](index.md)) + +Jump to: + +* [Add](#add) +* [Cancel](#cancel) +* [Find](#find) +* [List](#list) + +--- + +<a id="add"></a> +# Add Tag + +**Status:** implemented 20111006 + +**Required permissions:** "i" + +**Request:** `/json/tag/add[/name[/checkin[/value]]]` + +**Request options:** + +- `name=string` The tag name. +- `checkin=string` The checkin to tag. May be a symbolic branch name. +- raw=bool (=false) If true, then the name is set as it is provided by + the client, else it gets "sym-" prefixed to it. Do not use this + unless you really know what you're doing. +- `value=string` (=null) An optional value. While tags *may* have values + in fossil, it is unusual for them to have a value. (This probably + has some interesting uses in custom UIs.) +- `propagate=bool` (=false) Sets the tag to propagate to all descendants + of the given checkin. + +In CLI modes, the name, checkin, and value parameters may optionally be +supplied as positional parameters (in that order, after the command +name). In HTTP mode they may optionally be the 4th-6th path elements or +specified via GET/`POST.envelope` parameters. + +**Response payload example:** + +```json +{ +"name":"my-tag", +"value":"abc", +"propagate":true, +"raw":false, +"appliedTo":"626ab2f3743543122cc11bc082a0603d2b5b2b1b" +} +``` + +The `appliedTo` property is the hash of the check-in to which the tag was +applied. This is the "resolved" version of the check-in name provided by +the client. + +<a id="cancel"></a> +# Cancel Tag + +**Status:** implemented 20111006 + +**Required permissions:** "i" + +**Request:** `/json/tag/cancel[/name[/checkin]]` + +**Request options:** + +- `name=string` The tag name. May optionally be provided as the 4th path + element. +- `checkin=string` The checkin to untag. May be a symbolic branch name. + May optionally be provided as the 5th path element. + +In CLI modes, the name and checkin parameters may optionally be supplied +as positional parameters (in that order, after the command name) or +using the `-name NAME` and `-checkin NAME` options. In HTTP mode they may +optionally be the 4th and 5th path elements. + +**Response payload:** none (resultCode indicates failure) + + +<a id="find"></a> +# Find Tag + +Fetches information about artifacts having a particular tag. + +Achtung: the output of this response is based on the HTML-mode +implementation, but it's not yet certain that it's exactly what we want +for JSON mode. The request options and response format may change. + +**Status:** implemented 20111006 + +**Required permissions:** "o" + +**Request:** `/json/tag/find[/tagName]` + +The response format differs somewhat depending on the options: + +- `name=string` The tag name to search for. Can optionally be the 3rd + path element. +- `limit=int` (defalt=0) Limits the number of results (0=no limit). + Since they are ordered from oldest to newest, the newest N results + will be returned. +- `type=string` (default=`*`) Searches only for the given type of + artifact (using fossil's conventional type naming: ci, e, t, w.) +- `raw=bool` (=false) If enabled, the response is an array of hashes + of the requested artifact type; otherwise, + it is an array of higher-level objects. If this is + true, the "name" property is interpreted as-is. If it is false, the + name is automatically prepended with "sym-" (meaning a branch). + (FIXME: the current semantics are confusing and hard to remember. + Re-do them.) + +**Response payload example, in RAW mode: (expect this format to change +at some point!)** + +```json +{ +"name":"sym-trunk" +"raw":true, +"type":"*", +"limit":2, +"artifacts":[ + "a28c83647dfa805f05f3204a7e146eb1f0d90505", + "dbda8d6ce9ddf01a16f6c81db2883f546298efb7" + ] +} +``` + +Very likely todo: return more information with that (at least the +artifact type and timestamp). Once the `/json/artifact` family of bits is +finished we could use that to return artifact-type-dependent values +here. + +**Response payload example, in non-raw mode:** + +``` +{ +"name":"trunk", +"raw":false, +"type":"*", +"limit":1, +"artifacts":[{ + "uuid":"4b0f813b8c59ac8f7fbbe33c0a369acc65407841", + "timestamp":1317833899, + "comment":"fixed [fc825dcf52]", + "user":"ron", + "eventType":"checkin" + }] +} +``` + +<a id="list"></a> +# List Tags + +**Status:** implemented 20111006 + +**Required permissions:** "o" + +**Request:** `/json/tag/list[/checkinName]` + +Potential fixme: we probably have too many different response formats +here. We should probably break this into multiple subcommands. + +The response format differs somewhat depending on the options: + +- `checkin=string` Lists the tags only for the given CHECKIN (can be a + branch name). If set, includeTickets is ignored (meaningless in this + combination). This option can be set as either a GET/`POST.payload` + option, as the last element of the request path, e.g. + `/json/tag/list/MYBRANCH` *or* with `POST.payload` set to a string + value. +- `raw=bool` (default=false) uses "raw" tag names +- `includeTickets=bool` (default=false) Determines whether `tkt-` tags + are included. There is one of these for each ticket, so there can be + many of them (over 900 in the main fossil repo as of this writing). + +**Response format when raw=false and no checkin is specified:** + +```json +{ +"raw":false, +"includeTickets":false, +"tags":[ + "bgcolor", + "branch", + "closed", + …all tag names... + ] +} +``` + +Enabling the `raw` option will leave the internal `sym-` prefix on tags +which have them but will not change the structure. If `includeTickets` is +true then `tkt-` entries (possibly very many!) will be included in the +output, else they are elided. + +**General notes:** + +The `tags` property will be null if there are no tags, every non-empty +repo has at least one tag (for the trunk branch). + +**Response format when raw=false and checkin is specified:** + +```json +{ +"raw":false, +"tags":{ + "json":null, + "json-multitag-test":null + } +} +``` + +The `null`s there are the tag values (most tags don't have values). + +If `raw=true` then the tags property changes slightly: + +```json +{ +"raw":true, +"tags":{ + "branch":"json", + "sym-json":null, + "sym-json-multitag-test":null + } +} +``` + +TODO?: change the tag values to objects in the form +`{value:..., tipUuid:string, propagating:bool}`. |