Chapter 6. Naruto Rest Protocol

Prev		Next

Table of Contents

Requests
Responses
Exception Responses

Ack
Attributes
Decimal
Exception
Forum
Forums
Id
Nak
Topic
Topics
User

This protocol is implemented by the RestNaruto and RestNarutoService classes. Those classes should be used wherever possible so that future protocol changes can be dealt with seamlessly.

This chapter is dedicated to the REST protocol as it is deployed for the Naruto project. The intended audience for this document is either a protocol developer or a developer in a language besides PHP wishing to connect with this protocol.

1. Protocol Basics

Requests
Responses
Exception Responses

Requests

All requests can use either the GET or POST HTTP method. However, methods containing sensitive information should use the POST method so the information does not appear in web logs and is a little more secure.

All requests contain the HTTP header X_WEBPLANK_VERSION, the Naruto Client version, and X_WEBPLANK_AUTH, the caller's authentication info produced by the NatutoCredentials class.

The PATH_INFO is used to identify the Naruto method being called. For example, /GetForumList is identified a getForumList(). Most of them are obvious, but some methods may differ for obscurity or versioning. See the METHOD_* constants in the NaturoConstants class for the full list.

All requests contain the seq query parameter which is a client-unique transaction number. This parameter to help line up requests and responses.

Passwords in Requests

There are currently no passwords in requests. However, in the future, the may be.

Whenever possible passwords should not be sent over the network. With the use of the NarutoCredentials, the sending of the caller's password is avoided.

Rather than sending a plain text passwords in these cases, a non-trivial 2-way encoded algorithm is used and additionally the HTTP POST method should used to reduce visibility. A reversible algorithm, no matter how clever, can ultimately be reversed; so there is no substitute for a secure network tunnel.

Responses

All responses are in the forum of XML messages. Every method will either return the expected response or an Exception response. All responses have the following layout

<Naruto xmlns:naruto="http://naruto.sourceforge.net/rest">
  <ResponseType version="0.0.1" seq="89365064">
    ...
  </ResponseType>
</Naruto>

Element Naruto - The root element is always Naruto.
Element ResponseType - The element name will be replaced with the appropriate method response name, like GetForumListResponse.
Attribute version - The Naruto version deployed on the server.
Attribute seq - The sequence number passed in the request.

Exception Responses

A typical XML exception response is shown below. See the E_* constants in the NaturoConstants class for the full list of error codes, but be aware that new codes could be added.

<Naruto xmlns:naruto="http://naruto.sourceforge.net/rest">
  <Exception version="0.0.1" seq="89365064">
    <code>2</code>
    <message>User hacker invalid.</message>
  </Exception>
</Naruto>

The REST protocol service code may only throw the E_PROTO and E_COMM exceptions; however, it will return any exception it receives from the Naruto implementation it is configured to use. For example. E_AUTH could be thrown if the caller is not authenticated by the message board.

The following exception message demonstrates the case where there are secondary exception details.

<Naruto xmlns:naruto="http://naruto.sourceforge.net/rest">
  <Exception version="0.0.1" seq="19107746">
    <code>2</code>
    <message>Could not authenticate user</message>
    <secondarySource>ssoService</secondarySource>
    <secondaryCode>SSO123</secondaryCode>
    <secondaryMessage>Remote host unavailable</secondaryMessage>
  </Exception>
</Naruto>

2. Methods

Table 6.1. Rest Method Quick List

Request Path	Request Parameters	Response
/GetForumList	seq, [parentId], [userName]	<GetForumListResponse> <Forums/> </GetForumListResponse>
/GetTopicList	seq, forumId, [limit], [offset], [maxAge], [userName]	<GetTopicListResponse> <Topics/> </GetTopicListResponse>
/GetTopic	seq, forumId, topicId [userName]	<GetTopicResponse> <Topic/> or <Nak/> </GetTopicResponse>
/GetRecentTopics	seq, [limit], [maxAge], [userName]	<GetRecentTopicsResponse> <Topics/> </GetRecentTopicsResponse>
/AddForumTopic	seq, forumId, topic, body, [userName]	<AddForumTopicResponse> <Id/> </AddForumTopicResponse>
/AddTopicPost	seq, forumId, topicId, subject, body, [userName]	<AddTopicPostResponse> <Ack/> </AddTopicPostResponse>
/MergeTopics	seq, forumId, topicId, intoTopicId	<MergeTopicsResponse> <Ack/> or <Nak/> </MergeTopicsResponse>
/GetUnreadPrivateMessageCount	seq, [userName]	<GetUnreadPrivateMessageCountResponse> <Decimal/> </GetUnreadPrivateMessageCountResponse>
/GetUser	seq, userId [email]	<GetUserResponse> <User/> or <Nak/> </GetUserResponse>
/GetUserByName	seq, userName [email]	<GetUserByNameResponse> <User/> or <Nak/> </GetUserByNameResponse>
/GetUserBySession	seq, sessionId [email]	<GetUserBySessionResponse> <User/> or <Nak/> </GetUserBySessionResponse>

3. XML Elements

Ack
Attributes
Decimal
Exception
Forum
Forums
Id
Nak
Topic
Topics
User

Ack

The Ack element serves as a confirmation that a request has been completed or that the answer to the question is true.

<Ack/>

Attributes

The Attributes element encapsulates the NarutoDO class' attribute functionality. This is a sub element of the Topic and Forum elements.

<Attributes>
  <entry name="a">A</entry>
  ...
</Attributes>

Required Attributes: entry.name

Note

The list may be empty.

Decimal

The Decimal element represents the number value response to a question.

<Decimal>123</Decimal>

Exception

The Exception element encapsulates the NarutoException class.

<Exception version="0.0.1" seq="19107746">
  <code>2</code>
  <message>Could not authenticate user</message>
  <secondarySource>ssoService</secondarySource>
  <secondaryCode>SSO123</secondaryCode>
  <secondaryMessage>Remote host unavailable</secondaryMessage>
</Exception>

Required Elements: code, message

Forum

The Forum element encapsulates the NarutoForum and NarutoCategory classes.

<Forum type="category">
  <id>3</id>
  <name>Fun With Toys</name>
  <url>http://forum.com/forums?f=1</url>
  <parentID>1</parentId>
  <lastUpdated>1</lastUpdated>
  <topicCount>1</topicCount>
  <Attributes/>
</Forum>

Required Elements: id, name, url

Note

The forum type attribute is only set for when it is a category. A category is a special type of forum that only contains sub-forums and no topics.

Forums

The Forum element encapsulates and array NarutoForum and NarutoCategory objects.

<Forums>
  <Forum/>
  ...
</Forums>

Note

The list may be empty.

Id

The Id element represents the object id for a Topic, Forum or Category. It can be a string.

<Id>123</Id>

Nak

The Nak element indicates that the answer to the question is false.

<Nak/>

Topic

The Topic element encapsulates the NarutoTopic class.

<Topic>
  <id>3</id>
  <name>Fun Toys</name>
  <url>http://forum.com/topics?t=3</url>
  <forumD>1</forumId>
  <lastUpdated>1</lastUpdated>
  <postCount>1</postCount>
  <Attributes/>
</Topic>

Required Elements: id, name, url, forumId

Topics

The Topics element encapsulates and array NarutoTopic objects.

<Topics>
  <Topic/>
  ...
</Topics>

Note

The list may be empty.

User

The User element encapsulates the NarutoUser class.

<User>
  <id>3</id>
  <name>naruto</name>
  <url>http://forum.com/users?u=3</url>
  <email>naruto@forum.com</email>
  <Attributes/>
</User>

Required Elements: id, name, url