CommonSpot lets you run one or more commands (or methods) using an HTTP POST request. Calling the API this way is language independent, in the sense that it can be done from any programming environment that can generate HTTP POST requests and create basic XML (JavaScript, ColdFusion, .Net, PHP, and so on).
Command requests are made by sending an HTTP POST to one of the following URLs:
The URL to which you POST depends upon the method being invoked and its context. Most requests are sent to the loader URL within a site or subsite. Commands invoking server-level configuration components can also be sent to /commonspot/admin/loader.cfm. These server-level components are:
* These component can also be invoked through the {site}/{subsite} loader URL.
Requests to run other commands are made to loader.cfm in {site}/{subsite}, at the root or any number of subsite levels down. See the next section for more information.
Many commands operate within the context of a specific subsite, either because they act on it directly, or because the object they're working with is there. CommonSpot determines security settings, default and enforced keywords, and other environment properties according to the active subsite context for each command.
In CommonSpot 6.0, it was necessary to use the loader of the subsite you wanted to work with. Many subsite-related commands didn't provide any other way to specify which subsite you were referring to.
As of CommonSpot 6.1, subsite context is determined automatically from the passed Subsite ID or Subsite URL, or the passed Page ID, Image ID, or other object identifier. It no longer matters which subsite's loader received the request. This lets you act on multiple subsites or objects in multiple locations within the same request. For this reason, a number of subsite-related commands now have additional arguments to identify the target subsite.
See the 6.1 API Reference for details:
http://community.paperthin.com/APIHelp/610/
In many cases, to act on the current subsite, i.e., the one whose loader was used, you can pass empty string or 0 for Subsite ID or Subsite URL.
The following two parameters must be sent in the HTTP POST:
Before making an API request, the calling process must first log in and become authenticated using the normal CommonSpot interface. All subsequent requests need to pass the CFID and CFTOKEN or JSessionID cookies, so that ColdFusion can maintain the server-side session.
The HTTP API lets you send one or more commands and their arguments as a single XML command collection.
For each command in the collection:
Here is an example:
The first command in the collection runs the GetUserInfo() method of the Users component. No arguments are passed. The second command runs the getContributorTypes() method of the same component, passing a userID argument. The third runs the Reports.getSubsitePagesAndDirs() method, passing seven arguments.
CommonSpot executes these commands in the order in which they appear in the command collection. CommonSpot runs each command independently, so in most cases, commands that fail do not prevent later ones from executing. However, connection failures, expired login session, and some other global errors do prevent the whole collection from being processed.
While most commands are self-contained, you may need to split commands across two requests if one command updates memory variables that another one uses, but the effect of that change doesn't take place until the request completes.
CommonSpot returns the results for the entire command collection in a single XML <responsecollection>. Results from each command appear as separate <item> nodes within it. Here is an example:
The results structure will have a single <item> node for each command in the command collection. Each <item> node consists of a single <data> node and a single <status> node.
All field names are lower case. This is done to avoid case sensitivity issues in languages where that matters, for instance javascript.
The <data> node for a command <item> contains the actual value returned by that method call. It has a type attribute specifying the CommonSpot datatype of the result, and child nodes for each field in the returned data. For example, the data returned in the second <item> above is a Users_GetContributorTypes_Result structure, which has the following fields:
Fields in the returned data may also have a type attribute, indicating the datatype of that field. Fields with no type attribute are assumed to be strings. In the above example, the type attribute on canContribBeRemoved shows that it is a Boolean value, while the other fields have no type given, so they are strings.
Query result sets are represented as an array of <item> nodes, each with identical fields representing the columns in the query.
The <status> node for a command <item> contains information about the status of that command. Its main fields are:
LimitExceeded Boolean member, indicating whether more rows were available than that limit allowed the method to return.
For examples of how to invoke the Command API using HTTP XML, refer to:
To try it out yourself, see here: