Formatting requests to the API

In this topic:

Using curl as an example, here is the format for the API request:

curl --data "action=<action>&user=<username>&project=<project>&<parameters>[&ltoken=<auth_token>]" http(s)://<server>:<port>/review/api

where

  • <action> is one of the supported actions. See the API reference page for details (http://<klocwork_server_host>:<klocwork_server_port>/review/api).
  • <username> is your user name (required for all requests)
  • <project> is the name of a project on the Klocwork Server
  • <parameters> is option(s) for an action. See the examples below for details.
    For a list of acceptable keywords for use with the 'query' parameter of the Search action, see Searching in Validate.
  • <auth_token> is an authentication token from the ltoken. See the next section on authentication for details.

The API has full internalization support as long as the Content-Type is set correctly. Use curl's add-header command-line option to set the charset to UTF-8. For example:

curl --data "action=search&user=myself&query=アクション&project=a" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" http://localhost:8080/review/api

Authentication

As with any other operation involving the Klocwork Server, API requests must be authenticated.

  • If no access control method has been defined, all that is required is a user name, and that user name can be anything at all.
  • When using access control, however, both a user name and an authentication token must be provided. To print an authentication token and the user it was issued to for the specified server in JSON format, use kwauth --print-auth-info.

Authentication tokens are stored by kwauth and by Klocwork client applications in a special file in the user's home directory. You can find this file, called ltoken, as follows:

  • Windows:C:\Users\<user_name>\.klocwork\ltoken
  • Unix:~/.klocwork/ltoken

You can use a custom ltoken file location by setting the 'KLOCWORK_LTOKEN' environment variable. For more information, see Authentication using the ltoken.

If there is no ltoken file in your .klocwork directory, run kwauth to generate the file.

The ltoken file contains one or more text lines, each of which contains four pieces of information, separated by semi-colons:

<server>;<port>;<user_name>;<token>

Use the fourth piece of information as the authentication token in an API request. For example, the ltoken file for user bsmith, accessing server1 on the default port, 8080, might look like this:

server1;8080;bsmith;8244b24fbc50aa75e6f7c882d190616d577914501802ead4009a3e501df79350

The resulting curl request would look like this:

curl --data "action=projects&user=bsmith&ltoken=8244b24fbc50aa75e6f7c882d190616d577914501802ead4009a3e501df79350" http://server1:8080/review/api

Any script that accesses the API must read the ltoken file and extract the appropriate authentication token to append to its API requests. API applications must not write to the ltoken file. Instead, use kwauth to populate the ltoken file.