site/tags//* (GET)

Last updated
Save as PDF

Overview

Retrieve pages with tag

REST Method: GET
Method Access: public

Uri Parameters

Name	Type	Description
tagid	string	either an integer tag ID or "=" followed by a double uri-encoded tag name

Query Parameters

Name	Type	Description
include	string?	a comma separated list of elements to include, chose from 'tags' (default: none)
parentid	int?	only return pages that live under this page id. (default: all pages)
language	string?	filter pages by language (default: all languages)
authenticate	bool?	Force authentication for request (default: false)

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	Read access to the page is required
Not Found	404	The requested page could not be found

Message Format

Input: None

Output:

<tag value="{text}" id="{int}" href="{uri}" count="{int}">
    <type>{text|date|define}</type>
    <uri>{uri}</uri>
    <title>{text}</title>
    <pages count="{int}">
        <page id="{int}" href="{uri}">
            <uri.ui>{uri}</uri.ui>
            <title>{text}</title>
            <path>{text}</path>
            <namespace>{namespace}</namespace>
        </page>
    </pages>
</tag>

Implementation Notes

Tagging is a means of categorizing pages. There are currently three types of supported tags:

Date: Defines a date or date range for the page.
Define: Indicates that this is a defining tag. All other pages with a text tag having the same name will be marked as related to the page.
Text: Standard tag type.

C# Code Sample: Retrieve Pages Tagged with "sampletag"

This code sets a variable with the tag to retrieve, and executes the api call.

Sample Code

string tag= "=sampletag";
DreamMessage result = p1.At("site", "tags", tag).Get();
XDoc doc = result.AsDocument();
Console.WriteLine(doc.ToPrettyString());

Sample Response from executing Code

<tag value="sampletag" id="8753" href="http://base/@api/deki/site/tags/8753" count="1">
  <type>text</type>
  <uri>http://<server>/Special:Tags?tag=sampletag</uri>
  <title>sampletag</title>
  <pages count="1">
    <page id="54324" href="http://<server>/@api/deki/pages/54324?redirects=0">
      <uri.ui>http://<server>/<uri></uri.ui>
      <title>Contact Us</title>
      <path>Page/Path</path>
      <namespace>main</namespace>
    </page>
  </pages>
</tag>

Implementation notes

The tag variable must prefix the tag name with "=".

Curl Code Sample: Retrieve Tag Info

The following command retrieves a tag's data by the tag ID specified in the path (in this case tag.ID = 1):

Sample Code

curl -u username:password -i http://mindtouch.address/@api/deki/site/tags/1

Sample Response from executing Code

Example response where tag.ID = 11

Content-Type: application/xml

<tag value="real cool" id="11" href="http://192.168.59.128/@api/deki/site/tags/11" count="1">
  <type>text</type>
  <uri>http://192.168.59.128/Special:Tags?tag=real+cool</uri>
  <title>real cool</title>
  <pages count="1">
    <page id="565" href="http://192.168.59.128/@api/deki/pages/565?redirects=0">
      <uri.ui>http://192.168.59.128/Bar</uri.ui>
      <title>Bar</title>
      <path>Bar</path>
      <namespace>main</namespace>
    </page>
  </pages>
</tag>

Implementation notes

curl flags

-u: Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
-i: Outputs the HTTP response headers. Useful for debugging.