Invoking the API Using ColdFusion

You can call Command API methods directly from ColdFusion code. There are typically two scenarios in which you might do this:

You can only use CommonSpot’s direct ColdFusion API from a module located in a CommonSpot site directory on the same server. Otherwise, the site’s application.cfm module will not run, and required request processing will not take place.

You can, however, use CFHTTP to call the API via its HTTP XML interface, from any server. For more information see the section Invoking via HTTP/XML.

Before calling API commands, you must ask the user to log in within the same browser session.

Accessing API Components

To call a method, you must first obtain an instance of the API component whose methods you want to call, like this:


You can now call any number of that component's methods. The following example shows how you would call Users.getContributorTypes():

usersComponent = Server.CommonSpot.api.getObject('users');
contributorTypes = usersComponent.getContributorTypes(1000005);

Return Values

API methods return standard ColdFusion data types, for example, string, integer, structure, query, array, and so on. This documentation specifies the return type of each method, and its base type. For example, the Users.getContributorTypes method returns a result of type 'Users_GetContributorTypes_Result'. Its base type is structure, and it contains the following fields:

Special Return Types


When a method places an upper limit on the number of rows to return, CommonSpot returns data whose base type is RowLimitedQuery. This is a structure containing two members:

DetailedPage_Result is an example of a RowLimitedQuery type returned by multiple API methods.

When you call commands that return RowLimitedQuery results directly using CommonSpot's native ColdFusion API, CommonSpot returns the structure described above. However, when you call the same command through its HTML XML interface, CommonSpot moves LimitExceeded into the status structure, returning a standard query object as the <data> portion of the result, not the structure you get back from the native ColdFusion API.

Error Handling and Status Codes

CommonSpot will throw an error in the following situations:

As always, ColdFusion will also throw an error if a code execution problem occurs.

You can catch these errors like any other ColdFusion error, using CFTRY and CFCATCH. The error message and status code are members of the CFCATCH structure. For a complete listing of status codes, refer to Return Status Codes. The fields in the CFCATCH structure are:

Calling Context

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 run your code from a request directed to the subsite you wanted to work with. That's no longer true as of CommonSpot 6.1. See Invoking the API Using HTTP XML for more information, particularly the POST to loader URL and Subsite Context sections.