APIdoc XML Interface

Contents

• Introduction
• Authentication
• Responses
• Requests
  • currenttimestamp
  • getuser
  • getusercookie
  • search

Introduction

The APIdoc XML interface is a REST interface. Requests are made using simple HTTP GET and POST requests. Responses are returned as simple XML documents.

If you do use the XML interface, please use a descriptive User-Agent in the requests. The User-Agent should ideally contain a URL where more information about the client application can be found, or an email address where the author can be contacted.

If you write a client that uses the XML interface and would like a link from APIdoc.org, please contact us.

Authentication

Some requests, such as getuser, require authentication. Others, such as search will work either anonymously or with a login.

The authentication mechanism uses an HTTP cookie (the same mechanism that is used for the remember me facility on the site). The value of this cookie contains an encrypted representation of the user's email address and password.

To get a cookie value from an email address and password, use the getusercookie request. Once you have the value, submit it as the value of the login cookie:

GET /xml/getuser HTTP/1.0
Host: apidoc.org
Cookie: value=<urlencodedcookie>

Responses

The responses to all requests are all UTF-8 encoded XML documents with the following form:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>[ok|error]</status>
  <!-- Response Content -->
</response>

An error response will have a status of error and an error element with a message as the content:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>error</status>
  <error>
    <message>Error message</message>
  </error>
</response>

An ok status indicates the request was successful. Each request defines its own response content.

Requests

All requests are submitted using HTTP GET requests to URLs of the form http://apidoc.org/xml/requestname?param1=value1&param2=value2. Parameters are submitted in the query string. Parameter values must be URL encoded using UTF-8.

currenttimestamp

The currenttimestamp request returns the current time on the server. This is useful for making getusercookie requiests.

Request	currenttimestamp
URL	http://apidoc.org/xml/currenttimestamp
Authentication	Not required
Parameters	None
Response Content	<currentTimestamp>   <value>timestampValue</value> </currentTimestamp> Where timestampValue is the number of seconds since midnight GMT on January 1 1970.

getuser

The getuser request returns details about the authenticated user.

Request	getuser
URL	http://apidoc.org/xml/getuser
Authentication	Required
Parameters	None
Response Content	<user>   <name>name</name>   <emailAddress>emailAddress</emailAddress> </user> Where name and emailAddress are the name and email address of the authenticated user. If no login cookie or an invalid login cookie is provided, the error Not logged in will be returned.

getusercookie

The getuser request returns an authentication cookie for an email address and password.

Request	getusercookie
URL	http://apidoc.org/xml/getusercookie
Authentication	Not required
Parameters	emailAddress The user's email address. timestamp A timestamp (in seconds since midnight GMT on January 1 1970). Must be within the last two minutes according to the time on the server. The currenttimestamp request can be used to get a suitable value. passwordHash sha1(timestamp + ":" + sha1(emailAddress + ":" + password) Where sha1 is a SHA-1 hash function that hashes a string in UTF-8 encoding and returns a lowercase hex string. timestamp and emailAddress must correspond exactly to the values submitted as the timestamp and emailAddress parameters. password is the user's password.
Response Content	<usercookie>   <value>cookieValue</value> </usercookie> Where cookieValue is a cookie value that can be submitted as the value of the login cookie to indicate the authenticated user. If the timestamp is too old or the email address and password are not valid an error will be returned.

search

The search request performs a search.

Request	search
URL	http://apidoc.org/xml/search
Authentication	Optional. If authenticated, the user's aliases and groups will be available in the search. Otherwise, only the default aliases and groups can be used.
Parameters	query The search expression. first Optional. The first row to return (0 based - 0 is the first row, 1 is the second, etc). If not specified, the first count rows are returned. count Optional. The number of results (minumum 1, maximum 250) to return per page. If not specified, 50 results are returned per page.
Response Content	The response content consists of a search element containing a results element. The results element contains a number of result elements. For example: <search>   <results>     <result>       <score>1.00</score>       <iconURL>http://apidoc.org/pub/itemtypes/html-element.png</iconURL>       <typeDescription>HTML Element</typeDescription>       <item>         <id>11546</id>         <type>element</type>         <fullName>A</fullName>         <viewURL>http://apidoc.org/view/11546</viewURL>         <itemURL>http://apidoc.org/item/11546</itemURL>         <docset>           <id>8</id>           <type>html</type>           <name>HTML 4.01 Specification</name>           <shortName>HTML 4.01</shortName>           <url>http://apidoc.org/docset/8</url>         </docset>       </item>     </result>     <!-- Further result elements -->   <results> <search>