pages/{pageid}/tags (PUT)

Overview

Sets the tags on a page.

REST Method: PUT
Method Access: public

Uri Parameters

Name	Type	Description
pageid	string	either an integer page ID, "home", or "=" followed by a double uri-encoded page path

Query Parameters

Name	Type	Description
authenticate	bool?	Force authentication for request (default: false)
redirects	int?	If zero, do not follow page redirects.

Return Codes

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

Message Format

Input:

<tags>
    <tag value="{text}" />
    ...
</tags>

Output:

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

C# Sample: Set Tags

The following code example sets the tags on the page called "Page Title". A tag of each type is used (date, define, and text):

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc tagsDoc = new XDoc("tags")
    .Start("tag").Attr("value", "date:2007-08-29").End()
    .Start("tag").Attr("value", "define:this tag is a define").End();
    .Start("tag").Attr("value", "text tag").End()
p.At("pages", "=Page_Title", "tags").Put(tagsDoc);

Sample Response from executing Code

<tags count="3" href="http://deki-hayes/@api/deki/pages/31/tags">
    <tag value="text tag">
        <type>text</type> 
        <uri>http://deki-hayes/Special:Tags?tag=text+tag</uri> 
        <title>text tag</title> 
    </tag>
    <tag value="date:2007-08-29">
        <type>date</type> 
        <uri>http://deki-hayes/Special:Events?from=2007-08-29</uri> 
        <title>Wednesday, August 29, 2007</title> 
    </tag>
    <tag value="define:this tag is a define">
        <type>define</type> 
        <uri>http://deki-hayes/Page_Title</uri> 
        <title>this tag is a define</title> 
        <related count="1">
            <page id="29" href="http://deki-hayes/@api/deki/pages/29">
                <title>DekiWiki (Hayes)</title> 
                <path /> 
            </page>
       </related>
    </tag>
</tags>

Curl Sample: Set Tags

The following command attaches the list of tags defined in "tags.xml" to page "test".

Sample Code

curl -u username:password -H "Content-Type: application/xml" -T tags.xml -i http://mindtouch.address/@api/deki/pages/=test/tags

Implementation notes

curl flags

-u

Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-T: Sends a file using the PUT command.
-H: Overwrites or appends to HTTP header. In this case, the Content-Type needs to be set to "application/xml" for the server to process the request.

-i: Includes the HTTP response header in the output. Useful for debugging.

Example

We want to attach some tags of popular memes to page "Meme". The file memes.xml contains a list of meme tags.

memes.xml

Content-Type: application/xml

<tags>
	<tag value="rick roll"/>
	<tag value="star wars kid"/>
	<tag value="chocolate rain"/>
</tags>

Sample Code

curl -u username:password -H "Content-Type: text/xml" -T memes.xml -i http://192.168.168.110/@api/deki/pages/=Meme/tags

HTTP Response Headers

HTTP/1.1 200 OK
Date: Mon, 11 Jan 2010 21:47:29 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 671
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<tags count="3" href="http://192.168.168.110/@api/deki/pages/68/tags">
  <tag value="chocolate rain" id="4" href="http://192.168.168.110/@api/deki/site/tags/4">
    <type>text</type>
    <uri>http://192.168.168.110/Special:Tags?tag=chocolate+rain</uri>
    <title>chocolate rain</title>
  </tag>
  <tag value="rick roll" id="5" href="http://192.168.168.110/@api/deki/site/tags/5">
    <type>text</type>
    <uri>http://192.168.168.110/Special:Tags?tag=rick+roll</uri>
    <title>rick roll</title>
  </tag>
  <tag value="star wars kid" id="6" href="http://192.168.168.110/@api/deki/site/tags/6">
    <type>text</type>
    <uri>http://192.168.168.110/Special:Tags?tag=star+wars+kid</uri>
    <title>star wars kid</title>
  </tag>
</tags>

Notes

Running the curl command again with a different list of tags will overwrite the existing list.