API Documentation For Service Provider Editions

API Documentation for Logaholic (SPE) Service Provider Editions]

---

The API for Logaholic Service Provider Editions (SPE API) provides a framework that allows you to integrate Logaholic user and profile management features into your existing back-end system.

The API has the following features:

• Install Logaholic core system (multi-license versions only)
• Add, Edit and Delete user accounts
• Add and Delete website profiles

General Considerations

The API is installed as a separate component, It is not part of the core Logaholic application and should not be placed inside the main logaholic directory on your server.

Since the API enables 'remote' access to user and profile management features, it could pose a security risk if installed incorrectly. The API can be accessed through HTTP GET requests or as a php command line program, depending on where you install it.

Contents

• API Installation
• Using the API
• Adding Users
• Editing Users
• Deleting Users
• Adding Profiles
• Deleting Profiles
• Installing Logaholic Core system

Installation

1. To install the Logaholic SPE API, simply copy the logaholic_api folder from your download file to a location on your server.

• If you want to be able to access the API's functions via HTTP requests, place the "logaholic_api" folder in a web accessible directory.
• If you only want command line access to the API's functions, choose an non web accessible location on your server and ensure the api folder has the appropriate permission levels.

2. Open the following file in an editor and enter the appropriate values.

The values in red above are examples and should be replaced with your actual values.

That's it. You are now ready to use the API for user and profile management tasks.

Using the API

In the examples below, we'll pretend the API files are installed in /var/www/logaholic_api and can be reached via http://localhost/logaholic_api/ and that we have set up 'test' to be the API password.

When accessing the API via HTTP, requests should look something like this:

When accessing the API via the command line shell, commands should look something like this:

The api_password parameter must be present in all requests. It may only be omitted if you are making requests via the command line only and have left the api_password variable blank in the config.php file. If left blank, any requests via HTTP will fail.

Possible values for action and other key/value pairs will be described below. For the sake of simplicity, we'll only provide examples of HTTP requests below, but these can all be transformed into the command line equivalents using the example above.

Adding Users

To add users to your logaholic system, you'll need to make a request using the following parameters:

Parameter	Value	Notes
action	adduser	Tells the API we want to add a user
username	string	- Any alphanumeric string up to 100 characters length - Also see SPE Login documentation
password	string	Any alphanumeric string up to 32 characters length
Optionally, you can add the following parameters:
fullname	string	- The users full name, e.g. John Doe - Any alphanumeric string up to 100 characters length
email	string	- The users email address - Any alphanumeric string up to 100 characters length
accessEditProfile	0 or 1	- Controls whether the user can Edit certain profile settings - 0 = No, 1 = Yes - Default 1
accessAddProfile	0 or 1	- Controls whether the user can add new profiles from the Logaholic UI - 0 = No, 1 = Yes - Default 0
accessUpdateLogs	0 or 1	- Controls whether the user can manually Update statistics from the Logaholic UI - 0 = No, 1 = Yes - Default 0
active	0 or 1	- Controls whether the user account is active and can log in - 0 = No, 1 = Yes - Default 1
expires	0 or timestamp	- Controls whether the user account expires at a certain point in time. If left to '0', the account never expires. Otherwise, it expires when the unix timestamp value is met. - Default 0

A simple API request to add a user could look like this:

If the operation is successful the script will return the following string:

If the request fails, it will output an error message.

Editing Users

To Edit a Logaholic user account with the API, you can follow the instructions for adding users above, with these exceptions:

Parameter	Value	Notes
action	edituser	Tells the API we want to edit a user
new_username	string	- Any alphanumeric string up to 100 characters length - This can be the same as the original username, or a different string, but the parameter must be present

A simple API request to edit a user could look like this:

If the operation is successful the script will return the following string:

If the request fails, it will output an error message.

Deleting Users

To delete a user account, use the following parameters:

Parameter	Value	Notes
action	deleteuser	Tells the API we want to delete a user
username	string	The username of the user you want to delete

A simple API request to delete a user could look like this:

If the operation is successful the script will return the following string:

If the request fails, it will output an error message.

Adding Profiles

When adding a website profile to Logaholic through the API, it's important to note the following:

• If no profile name is given, the API automatically generated a profile name based on the site's (sub) domain. For example, adding a profile for www.test-me.com, would generate a profile name called 'wwwtestmecom'.
• Using the API only a limited number of profile settings can be set. Other settings must be changed via the regular UI.
• When a log file location is not provided, we assume the profile will be using javscript tags to collect data.

To add a website profile via the API, you can use the following parameters:

Parameter	Value	Notes
action	addprofile	Tells the API we want to add a profile
username	string	- The username of the account that owns this site - The username must exist, so always add users before adding profiles
site	string	Any (sub)domain, e.g. www.mysite.com
Optionally, you can add the following parameters:
profile_name	string	- The name you want to give this profile in the logaholic system - If this parameter is missing, the profile name is automatically derived from the site parameter
logfilelocation	string	- The system path to the log file or the directory that contains the log files for this site - If this parameter is missing, the profile is set up to use Javascript data collection
splitlogs	0 or 1	- Indicates whether the logfilelocation parameter points to a single log file, or to a directory containing multiple log files - 0 = Single file, 1 = Directory (multiple files) - Default 1
splitfilter	string or (regular expression)	This parameter can be used to avoid unwanted files in the directory to be analyzed. For example, if all your log file names start with "access_log", use that as the value for this parameter. Only files that (partially) match this value will be analyzed. Leave this blank if all files in the logfilelocation directory need to be analyzed. If you require more complex filtering capabilities, you may also enter a regular expression, between parenthesis. For example (^www\.[xyz|abc.xyz].log.*)

An API request to add a profile could look like this:

If the operation is successful, the script will return the following string:

If the request fails, it will output an error message.

Deleting Profiles

To delete a profile from the logaholic system, you can use the following parameters:

Parameter	Value	Notes
action	deleteprofile	Tells the API we want to delete a profile
username	string	- The username of the account that owns this site - The username must exist, or the profile will not be deleted
site	string	The (sub)domain you want to delete the Logaholic profile for

An API request to delete a profile could look like this:

If the operation is successful the script will return the following string:

If the request fails, it will output an error message.

Installing Core Logaholic system

Your logaholic download file will contain 2 main directories:

1. Copy the logaholic folder to the location on your server where you want to install the Logaholic Web Analytics system
2. Make the logaholic/files directory writeable, see regular install procedure step 2.
3. Install the logaholic_api folder on your server, see API Installation.

Once the above is done, you can install the main Logaholic system using an API request like this:

If the operation is successful the script will return the following string:

If the request fails, it will output an error message.