Topic

From Hypertopic

Jump to: navigation, search

Contents

Document Format of Topic

Topic DTD 

<?xml version="1.0" encoding="UTF-8"?> 
<!ELEMENT topic (viewpoint?, (relatedTopic | entity | remoteEntity)*)>
<!ELEMENT viewpoint (#PCDATA)>
<!ELEMENT relatedTopic (#PCDATA)>
<!ELEMENT entity (#PCDATA)>
<!ELEMENT remoteEntity (#PCDATA)>
<!ATTLIST topic 
	href CDATA #IMPLIED
	name CDATA #IMPLIED
>
<!ATTLIST viewpoint 
	href CDATA #REQUIRED
> 
<!ATTLIST relatedTopic
	href CDATA #REQUIRED
	relationType (includes|includedIn|referTo|seeAlso) "includes"
	action (delete|insert) #IMPLIED
>
<!ATTLIST entity 
	href CDATA #REQUIRED
	action (delete|insert) #IMPLIED
>
<!ATTLIST remoteEntity 
	href CDATA #REQUIRED
>

Example of Topic 

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
 <topic name="World Wide Web">
   <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">Software features</viewpoint>
   <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/2/">Web browser</relatedTopic>
   <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/3/">Web server</relatedTopic>
   <entity href="http://tech-ada.utt.fr/entity/www/">html specification</entity>
 </topic>

XML structure of Topic

XPath Cardinality Description
/topic/@href Optional Topic URI
/topic/@name Optional Topic Name
/topic/viewpoint/ 1 Viewpoint which the topic belongs to
/topic/viewpoint/@href Required Viewpoint URI
/topic/relatedTopic * Topics linked to the current topic Note: The related topics should be in the same viewpoint.
/topic/relatedTopic/@relationType Required The relation type between the current topic and the related topic. It could be "includes/includedIn/referTo/seeAlso", default is "includes".
/topic/relatedTopic/@href Required Related topic URI.
/topic/entity * Entities described by the topic.
/topic/entity/@href Required Entity URI.

Topic RelationShips

An example of topics' relationships

The following table shows the representation of Topic "Topic D". 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
<topic href="http://tech-ada.utt.fr/viewpoint/1/topic/1/" name="Topic D">
    <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">HyperTopic Demonstration</viewpoint>
    <relatedTopic relationType="includedIn" href="http://tech-ada.utt.fr/viewpoint/1/topic/2/">Topic B</relatedTopic>
    <relatedTopic relationType="referTo" href="http://tech-ada.utt.fr/viewpoint/1/topic/3/">Topic C</relatedTopic>
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/4/">Topic E</relatedTopic>
    <relatedTopic relationType="seeAlso" href="http://tech-ada.utt.fr/viewpoint/1/topic/5/">Topic F</relatedTopic>
    <entity href="http://tech-ada.utt.fr/entity/AMAYA/" />
</topic>

The following table shows the representation of Topic "Topic E" 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
<topic href="http://tech-ada.utt.fr/viewpoint/1/topic/4/" name="Topic E">
    <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">HyperTopic Demonstration</viewpoint>
    <relatedTopic relationType="includedIn" href="http://tech-ada.utt.fr/viewpoint/1/topic/1/">Topic D</relatedTopic>
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/7/">Topic H</relatedTopic>
    <entity href="http://tech-ada.utt.fr/entity/AMAYA/" />
</topic>

Add a New Topic

Add a new topic.

Arguments

viewpointid (Required)

The id of the viewpoint which the topic belongs to.

Note: This method requires an HTTP POST request.

Example Request 

POST /viewpoint/1/topic/

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
<topic name="World Wide Web">
  <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">Software features</viewpoint>
</topic>

Example Response 

Location: /viewpoint/1/topic/1/

Status Codes

201: Created

The request has been fulfilled and resulted in a new resource being created.

400: Bad Request

The request could not be understood by the server due to malformed syntax.

500: Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503: Service currently unavailable

The requested service is temporarily unavailable.

Delete a Topic

Delete a specific topic. To keep the history trace, this method will not delete the topic instead it will set the specific topic as inactive.

Arguments

viewpointid (Required)

The id of the viewpoint which the topic belongs to.

topicid (Required)

The id of the topic to delete.

Note: This method requires an HTTP DELETE request.

Example Request 

DELETE /viewpoint/1/topic/1/

Example Response

This method has no specific response - It returns an empty sucess response if it completes without error. 

200 OK

Status Codes

200: OK

The request has succeeded.

404: Not Found

The server has not found anything matching the Request-URI.

500: Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503: Service currently unavailable

The requested service is temporarily unavailable.

Get a Topic

Get a specific topic information with related topics and entities.

Arguments

viewpointid (Required)

The id of the viewpoint which the topic belongs to.

topicid (Required)

The id of the topic to fetch detail information for.

Note: This method requires an HTTP GET request.

Example Request 

GET /viewpoint/1/topic/1/

Example Response 

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
<topic name="World Wide Web">
  <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">Software features</viewpoint>
  <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/2/">Web browser</relatedTopic>
  <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/3/">Web server</relatedTopic>
</topic>

Status Codes

200: OK

The request has succeeded.

404: Not Found

The server has not found anything matching the Request-URI.

500: Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503: Service currently unavailable

The requested service is temporarily unavailable.

Update a Topic

Modify a specific topic.

Arguments

viewpointid (Required)

The id of the viewpoint which the topic belongs to.

topicid (Required)

The id of the topic to update.

Note: This method requires an HTTP PUT request.

Example Request 

PUT /viewpoint/1/topic/1/

<?xml version="1.0" encoding="UTF-8"?> 
<topic name="World Wide Web">
    <viewpoint href="http://tech-ada.utt.fr/viewpoint/1/">Software features</viewpoint>
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/2/">Web browser</relatedTopic>
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/3/">Web server</relatedTopic>
    <relatedTopic relationType="includedIn" href="http://tech-ada.utt.fr/viewpoint/1/topic/4/">Internet</relatedTopic>
</topic>

Example Response

This method has no specific response - It returns an empty sucess response if it completes without error. 

205 Reset Content

Status Codes

205: Reset Content

The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

400: Bad Request

The request could not be understood by the server due to malformed syntax.

404: Not Found

The server has not found anything matching the Request-URI.

500: Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503: Service currently unavailable

The requested service is temporarily unavailable.

Update a Topic Partial

Modify a specific topic's relation ship with other topics.

Arguments

viewpointid (Required)

The id of the viewpoint which the topic belongs to.

topicid (Required)

The id of the topic to update.

Note: This method requires an HTTP POST request.

Example Request

The following example shows how to create relation between topic #1 and topic #2, and delete relation between topic #1 and topic #3. 

POST /viewpoint/1/topic/1/

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE topic SYSTEM "http://tech-ada.utt.fr/validator/dtd/topic.dtd">
<topic name="World Wide Web">
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/2/" action="insert">Web browser</relatedTopic>
    <relatedTopic relationType="includes" href="http://tech-ada.utt.fr/viewpoint/1/topic/3/" action="delete">Web server</relatedTopic>
</topic>

Example Response

This method has no specific response - It returns an empty sucess response if it completes without error. 

205 Reset Content

Status Codes

205: Reset Content

The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

400: Bad Request

The request could not be understood by the server due to malformed syntax.

404: Not Found

The server has not found anything matching the Request-URI.

500: Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503: Service currently unavailable

The requested service is temporarily unavailable.

Traces

Operation

Retrieved from "http://www.hypertopic.org/index.php/Topic"
Personal tools