API Descriptions

API Descriptions
	Overview of Web Services APIs

Each API is described as a list of methods. Each method description has the following sections:

Method Name

This section specifies the name of the operation. For the SOAP implementation, this is the SOAP operation name. For the ASP.NET implementation, the operation name is the name of the ASP.NET page that implements that operation. When invoking the operation on the ASP.NET implementation, the request should be made to an address constructed by concatenating the base URL of the service, a forward slash, the operation name and string ".aspx". For example, if you have the Topic Map Web Service installed on your local machine at http://localhost/tmws, then the URL for the GetTopicMaps operation is http://localhost/tmws/GetTopicMaps.aspx.

Parameters

This section lists the input parameters for the operation. All parameters are assumed to be REQUIRED unless they are explicitly flagged with as OPTIONAL. All parameter are assumed to be string literals, unless the parameter description specifies a different type.

For a SOAP invocation, each parameter maps to an element in the SOAP input message for the operation where the element name is the same as the parameter name.

For an ASP.NET implementation, the mapping of parameters depends upon how the operation is invoked. All ASP.NET implementations support both invocation using an HTTP GET and invocation using an HTTP POST. When invoking the operation using an HTTP GET, each parameter should be provided as a query parameter in the URL. When invoking the message using an HTTP POST, the body of the POST request must contain only an XML document. The XML document POSTed to the ASP.NET page must use the following syntax:

<request>
  <param name="PARAMETER NAME"> VALUE </param>
</request>

The request element is the outer wrapper for the request parameters. Each parameter is specified using a param element. The name attribute of the param element is required and must be set to the name of the parameter whose value is specified. The content of the param element must be the parameter value. The param element may contain an XML fragment if allowed by the parameter type.

Example 1. POST Invocation Examples

The following examples relate to invocation of methods exposed by the NetworkedPlanet Topic Map Web Service.

To invoke a method that takes no parameters, post an empty requets element. For example to invoke the GetTopicMaps operation you could post the following content to the GetTopicMaps.aspx page:

<request />

To invoke the GetTopicBySubjectIdentifier operation to get the topic with the subject identifier http://www.example.com/mypsi/ in the topic map named 'mytopicmap', post the following content to the GetTopicBySubjectIdentifier.aspx page:

<request>
  <param name="topicmap">mytopicmap</param>
  <param name="locator">http://www.example.com/mypsi/</param>
</request>

To invoke the Save operation to update a topic in the topic map 'mytopicmap', post the following content to the Save.aspx page (the full content of the tmfragment parameter is ommitted for brevity):

<request>
  <param name="topicmap">mytopicmap</param>
  <param name="tmfragment">
    <topicmap xmlns="http://www.networkedplanet.com/2005/01/topicmap/data/">
      ...
    </topicmap>
  </param>
</request>

A few operations take an array of strings as a parameter. To make these requests, simply wrap each separate string parameter in its own param element. For example to delete two topics from a topic map (an operation which takes an array of topic object identifiers in the parameter named "oids"), post the following content to the DeleteTopics.aspx page:

<request>
  <param name="topicmap">mytopicmap</param>
  <param name="oids">1234</param>
  <param name="oids">5678</param>
</request>

Tip

A request element can contain its param elements in any order - you do not have to match the order in which the parameters are specified on an operation and you can mix lists of values for string array parameters in with other parameter specifications.

Returns

The Returns section describes what results are returned by the operation if it is successful, and how those results are represented. The return result from any operation is always an XML document. For operations that only update the topic map (and do not request information from it), the SOAP response body content may differ from the HTTP interface response body, in that a successful SOAP operation simply returns an empty response body (using the normal SOAP headers to indicate success) whereas the HTTP interface will always return an XML document in the response body as well as an HTTP status code indicating success.

Errors

The Errors section list operation-specific error conditions. Each error condition is described in a table that shows the error code, the condition under which the error is raised and the structure of any error-specific details.

For a SOAP implementation of an operation, an error is notified to the caller as a SOAP fault. The fault element will contain a faultstring value which contains an error message, and a faultdetail element which will contain the full error description XML document as described below.

For an ASP.NET implementation, successes or failed execution of an operation will be indicated using HTTP status codes.

200 (OK) for completely successful operations.

403 (Bad Request) for failed or partially successful operations, where failures occurred due to bad input being supplied by the user.

500 (Internal Server Error) for failed or partially successful operation, where failures occurred due to circumstances outside of the users control.

For invocations which require multiple operations to be executed (for example passing multiple topic IDs to DeleteTopics), if any of the operations fail then an error status code will be returned. The caller must check the body of the response which will either be the XML document described in the Returns section, or will be an error description XML document as described below to determine which parts of the operation succeeded.