4.2. API Basics: URL, Methods, Return Formats, Authentication
How to Enable the API
By default both the public and private API's are disabled. You must enable them to use them in Admin->Settings->Web Services API
API URL
The API is accessed from the URL: http://www.domain.com/api/index.php.
Specific methods are accessed by using the "method" query string parameter. Example:
http://www.domain.com/api/index.php?method=request.get
Public vs Private
The HelpSpot API contains both public and private methods. Private methods require authentication, public do not. Private methods are those that start with "private". For example: private.filter.get
Return Format
3 return types are currently supported:
- XML (this is the default)
- JSON
- Serialized PHP
You can specify the return type you wish to receive back from the API by adding the "output" query string parameter to your API URL. If you want to receive XML then you do not need to specify the output as that is the default. Example:
/api/index.php?method=request.get&output=json
The "output" parameter will accept xml, json, or php as valid values.
Private API Authentication
Private API requests require a staff members email address (or username if using Black Box) and password. There are 2 ways to pass this information to the API.
1. HTTP Basic Authentication
You may pass in the username and password via HTTP basic authentication. Libraries such as cURL generally support this.
2. URL Parameters
The information may be passed directly in the URL as parameters. Example:
/api/index.php?method=request.get&username=tim@domain.com&password=abc123
Character Set
The API currently expects iso-8859-1 data. Additional character sets may be supported in the future.
Version Information
You may always retrieve the current and minimum versions of the API by calling the "version" method. Example:
/api/index.php?method=version
/api/index.php?method=private.version (note this requires authentication as all private methods do)
This method will return:
- version - The current version of the API the installation is using.
- min_version - The minimum version of the API a client application must support in order to operate correctly with the server installation. For instance, if the server API is currently 3.0 with a minimum version of 2.0 then a client written to use the 1.0 API would not function properly. Clients should check this value before using the API.
Errors
If an error occurs instead of the methods XML an error XML data will be returned instead. The data is in this format:
<?xml version="1.0" encoding="iso-8859-1"?> <errors> <error> <id>2</id> <description>User authentication failed</description> </error> </errors>
More than one error tag may occur in the root errors tag.
If the API type being accessed (public or private) is not enabled in Admin->Settings an error in the following format will be returned.
<?xml version="1.0" encoding="iso-8859-1"?> <reply>Private API not enabled</reply>
Errors always return a "400 Bad Request" HTTP header as well.
The Easiest Way to Try the API
The easiest way to start is by using curl or even FireFox to try some of the public API calls. Make sure the public API is enabled, then try these URL's:
- Get the version:
/api/index.php?method=version - List the public knowledge books:
/api/index.php?method=kb.list - Get an existing request in the system:
/api/index.php?method=request.get&accesskey=####(use the access key for the request)