Fossil

JSON API: /tag
Login

(⬑JSON API Index)

Jump to:


Add Tag

Status: implemented 20111006

Required permissions: "i"

Request: /json/tag/add[/name[/checkin[/value]]]

Request options:

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:

{
"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.

Cancel Tag

Status: implemented 20111006

Required permissions: "i"

Request: /json/tag/cancel[/name[/checkin]]

Request options:

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)

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:

Response payload example, in RAW mode: (expect this format to change at some point!)

{
"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"
 }]
}

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:

Response format when raw=false and no checkin is specified:

{
"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:

{
"raw":false,
"tags":{
  "json":null,
  "json-multitag-test":null
 }
}

The nulls there are the tag values (most tags don't have values).

If raw=true then the tags property changes slightly:

{
"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}.