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:

• From a ColdFusion module running as part of a page request; for example, a render handler, custom script, base template, and so on
• From a ColdFusion module located within a site's directory hierarchy

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:

Server.CommonSpot.api.getObject('{component_name}');

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:

• canContribBeRemoved
• reasonList
• typeList
• userType

Special Return Types

RowLimitedQuery

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:

• ResultQuery - a standard ColdFusion query object
• LimitExceeded - a Boolean value indicating whether more rows were available than the method was allowed to return

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:

• Inappropriate data is passed as arguments
  Example: A passed argument value is a non-numeric string when the method expects an integer.
• The call violates a CommonSpot business rule
  Example: You try to delete the last administrator.
• An attempt is made to run the command in an incorrect context
  Example: From a ROPS, you try to access a method that is only available on an authoring server.

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:

• Message - Text describing the error; for example, 'One or more invalid arguments detected'.
• MethodName - The name of the method that failed.
• Reason - A structure describing the reason for the error.
• ReasonCode - The main status code.
• ReasonSubCode - A code that further identifies the error.
• StackTrace - The ColdFusion stack trace.
• TagContext - The ColdFusion tag context array.
• Type - A string describing the type of error; for example, com.paperthin.common.csruntimeexception.CSValidationException.

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.