Page last modified 00:03, 22 Nov 2008 by petee
Table of contents
- 1. GET:site/tags
- 2. Overview
- 2.1.1.1. Query Parameters
- 2.1.1.2. Return Codes
- 3. Message Format
- 4.
- 5. Implementation Notes
- 6. Code Samples
- 7. GET:site/tags/{tagid}
- 8. Overview
- 8.1.1.1. Uri Parameters
- 8.1.1.2. Query Parameters
- 8.1.1.3. Return Codes
- 9. Message Format
Part of the Lyons release will include improvments to the tagging API.
NOTE: this spec is a work in progress
GET:site/tags
Overview
public. Retrieve all tags on the wiki (with permissions applied)
Query Parameters
| Name | Type | Description |
| type | string? | type of the tag (text | date | user | define) (default: all types) |
| to | string? | For type = date, limit the results by date. If only to but no from is specified, show tags from curent time through to. Ex: 2008-12-30 |
| from | string? | For type = date, limit the results by date. If only from but no to is specified, show tags for from through from + 30 days |
| pages | bool? | Display pages tagged with given tag. |
Return Codes
| Name | Value | Description |
| BadRequest | 400 | Invalid input parameter or request body |
| NotFound | 404 | Requested page could not be found |
| Ok | 200 | The request completed successfully |
Message Format
Output: with ?pages=0
<tags count="4">
<tag value="define:tagtest" href="http://dekidev/@api/deki/site/tags/5" count="1">
<type>define</type>
<uri>http://dekidev/User:Admin/Tag_Test</uri>
<title>tagtest</title>
</tag>
<tag value="blah" href="http://dekidev/@api/deki/site/tags/6" count="2">
<type>text</type>
<uri>http://dekidev/Special:Tags?tag=blah</uri>
<title>blah</title>
</tag>
<tag value="date:2008-11-12" href="http://dekidev/@api/deki/site/tags/7" count="1">
<type>date</type>
<uri>http://dekidev/Special:Events?from=2008-11-12</uri>
<title>Wednesday, November 12, 2008</title>
</tag>
<tag value="date:2008-11-21" href="http://dekidev/@api/deki/site/tags/8" count="2">
<type>date</type>
<uri>http://dekidev/Special:Events?from=2008-11-21</uri>
<title>Friday, November 21, 2008</title>
</tag>
</tags>
Output: with ?pages=1&type=date&from=2008-1-1&to=2009-1-1
<tags count="2">
<tag value="date:2008-11-12" href="http://dekidev/@api/deki/site/tags/7" count="1">
<type>date</type>
<uri>http://dekidev/Special:Events?from=2008-11-12</uri>
<title>Wednesday, November 12, 2008</title>
<pages count="1">
<page id="35" href="http://dekidev/@api/deki/pages/35?redirects=0">
<title>User:Admin</title>
<path>User:Admin</path>
<namespace>user</namespace>
</page>
</pages>
</tag>
<tag value="date:2008-11-21" href="http://dekidev/@api/deki/site/tags/8" count="2">
<type>date</type>
<uri>http://dekidev/Special:Events?from=2008-11-21</uri>
<title>Friday, November 21, 2008</title>
<pages count="2">
<page id="34" href="http://dekidev/@api/deki/pages/34?redirects=0">
<title>Deki Wiki</title>
<path></path>
<namespace>main</namespace>
</page>
<page id="35" href="http://dekidev/@api/deki/pages/35?redirects=0">
<title>User:Admin</title>
<path>User:Admin</path>
<namespace>user</namespace>
</page>
</pages>
</tag>
</tags>
Implementation Notes
This feature can be used to generate a tag cloud as well as displaying chronotags. Displaying all tags with page information is an expensive operation since page permissions are applied.
Code Samples
The following code example retrieves all tags for a site
Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
p.At("site", "tags").Get();
GET:site/tags/{tagid}
Overview
public. Retrieve pages for a given tag
Uri Parameters
| Name | Type | Description |
| tagid | string | either an integer tag ID or "=" followed by a double uri-encoded tag title |
Query Parameters
| Name | Type | Description |
Return Codes
| Name | Value | Description |
| BadRequest | 400 | Invalid input parameter or request body |
| NotFound | 404 | Requested page could not be found |
| Ok | 200 | The request completed successfully |
Message Format
Output:
<tag value="define:tagtest" href="http://dekidev/@api/deki/site/tags/5" count="1">
<type>define</type>
<uri>http://dekidev/User:Admin/Tag_Test</uri>
<title>tagtest</title>
<pages count="1">
<page id="1691" href="http://dekidev/@api/deki/pages/1691?redirects=0">
<title>Tag Test</title>
<path>User:Admin/Tag_Test</path>
<namespace>user</namespace>
</page>
</pages>
</tag>
- Tag page
- What links here
Images 0
Viewing 1 of 1 comments: view all
#1
MaxM says:
I'd probably remove the tag/@count attribute and only keep it as /tag/pages/@count. Will the pages always be listed out for each tag when looking at multiple tags such as get:site/tags ? Perhaps when listing multiple tags leave in the <pages> element with a count but dont output the pages. Determining an accurate count with permissions applied can become really troublesome. Perhaps drop the count alltogether?
Posted 22:28, 17 Nov 2008
Viewing 1 of 1 comments: view all
You must login to post a comment.