Partners API Documentation

From Wiki

Jump to: navigation, search

Contents

Introduction

The 1H Partners API is an interface that allows our clients to automate certain operations, such as activating and removing licenses, adding sub-users to their account, etc. These actions can be performed via function calls to our API, sparing the need to manually log into your user's area and perform the desired action.


How to start using the API

If you are client of 1H and want to start using the API then you should first log into the Users Area and access the Manage API section. It is accessible from the 'My Services'->'Manage API' menu item. There you should click the [Enable API] button, which would cause a unique API code and key to be generated for you. These two strings are used for authentication in each API call that you are going to make ( the "auth_code" and "api_key" parameters ). You can also download our API client library from there (currently only offered in PHP) to save the time necessary for implementing your own API client. See the #API_Client section for more details.


How API calls work

The 1H Partners API works by accepting calls done via HTTP POST requests to https://api.1h.com/partners. The POST parameter that contains the call is named 'request' and should contain a JSON-serialized request object having the following format:

{
  "auth_code": "your_api_code",
  "api_key": "your_api_key",
  "payload": {
    "command": "command",
    "params":{ ["param1": "value1" [,"param2": "value2"[, ...]] }
  }
}

Responses follow similar format, with the response parameters hash varying, depending on the command and output:

- For Success:

{
  "response_code': 1,
  "response": { ["param1": "value1" [,"param2": "value2"[, ...]] }
}

- For Failure:

{
  "response_code': 0,
  "response": { 
    "err_no": error_code_integer,
    "err_string": "Error description" 
  }
}  


Example

Here is an example for an API call which activates a new license for the "Hive" product, which is going to be used on a machine with IP address 123.123.123.123 :

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_license",
    "params": { 
       "product": "Hive",
       "ip": "123.123.123.123" 
     }
  }
}

If your call has been successfully authenticated and processed you would receive a response which looks like this:

{
  "response_code': 1,
  "response": []
}

Otherwise, in case something went wrong, for example if you already have active license for that server IP, you would receive a response like this:

{
  "response_code' : 0,
  "response":
  {
    "err_no": 34,
    "err_string": "You already have Hive license for this IP." 
  }
}

Note that although the response parameters may or may not be present in successful responses, the "err_no" and "err_string" response parameters are always returned if the call failed (response_code = 0).


Users and sub-users

Each 1H client has a user which is created upon sign-up/approval. This is the main (or master) user of the account, which has full privileges and access to the Users Area. Unless a client is planning on reselling 1H products, or has some other need for partitioning his/her licenses into different groups, the main user is the only user he/she needs. However, since partners need to keep their clients' licenses in corresponding groups, sub-users are used to apply this kind of management.

Sub-uses are created via the add_user (#add_user) API call. The username of the newly created user can then be passed as parameter to commands such as add_license (#add_license) to specify that the new license is supposed to go under that sub-user.


API Commands

The following commands are supported in the current version (1.3.1) of the API:

add_user

Adds a new sub-user under your account. For more info on sub-users see the #Users_and_sub-users section above.

The new sub-user must be created with a unique username, otherwise the API would return an "existing user" error (code 17). See the #Error_codes section at the bottom for more details.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_user",
    "params": { 
       "username": "mysubuser01",
       "password": "s3cr3tp@$$",
       "email": "subuser01@mydomain.com",
       "name": "Subuser Subuserson" 
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }

update_user

Updates the details (like email and name) of a sub-user under your account. For more info on sub-users see the #Users_and_sub-users section above.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_user",
    "params": { 
       "username": "mysubuser01",
       "email": "subuser01_new@somenewdomain.com",
       "name": "Subusery Subusersky" 
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }

suspend_user

Suspends a sub-used under your account. For more info on sub-users see the #Users_and_sub-users section above.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "suspend_user",
    "params": { 
       "username": "mysubuser01"
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }


unsuspend_user

Unsuspends a suspended sub-used under your account. For more info on sub-users see the #Users_and_sub-users section above.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "unsuspend_user",
    "params": { 
       "username": "mysubuser01"
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }


add_license

Activates a new license for a given product and IP address.

The product name must be an existing 1H product (like 'Hive' or 'Guardian'), the IP address must be valid and you must not have an already active license for this product on the provided IP for this command to work. For more details on possible error conditions associated with this command see the #Error_codes section below.

Expected input parameters:


Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_license",
    "params": { 
       "product": "Hive",
       "ip": "123.123.123.123",
       "username": "mysubuser01",
       "label": "My machine 001"
     }
  }
}

or (without sub-user):

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_license",
    "params": { 
       "product": "Hive",
       "ip": "123.123.123.123",
       "label": "My machine 001"
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }

remove_license

Removes/cancels a license for a given product and IP address.

Expected input parameters:


Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "remove_license",
    "params": { 
       "product": "Hive",
       "ip": "123.123.123.123" 
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }


get_licenses

Returns list with information for all the licenses belonging to the caller.

If the optional "username" parameter is passed then only licenses belonging to the corresponding sub-user (if such) are returned. For more info on sub-users see the #Users_and_sub-users section above.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "get_licenses",
    "params": { 
       "username": null
     }
  }
}

Response parameters: Returns an array of license objects under the "licenses" response hash key (note that all the users' licenses are returned because "username" parameter is null):

{ 
  "response_code': 1, 
  "response": {
    "licenses": [
      {
        "product": "Hive", 
        "license_ip": "1.1.1.1", 
        "user": "myuser", 
        "description": "The machine in the closet :)", 
        "date_activated": "2010-09-08", 
        "date_expires": "2010-10-08", 
        "active": "0" 
      },
      {
        "product": "Guardian",
        "license_ip": "2.2.2.2",
        "user": "mysubuser01", 
        "description": null,
        "date_activated": "2010-09-30",
        "date_expires": "2010-10-30", 
        "active": "1" 
      }
    ]
  } 
}


add_portal

Creates a portal for a sub-user under your account

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "add_portal",
    "params": { 
       "username": "mysubuser01",
       "ip": "123.123.123.123",
       "portal_domain": "1h.myveryspecialdomain.com"
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }


update_portal

Updates a portal for a sub-user under your account

NOTE: You must either or both of the 'ip' and 'portal_domain' parameters. They cannot be both null.

Expected input parameters:

Sample call:

{
  "auth_code": "a1b2c3d4e5",
  "api_key": "0123456789abcde0123456789abcde",
  "payload": {
    "command": "update_portal",
    "params": { 
       "username": "mysubuser01",
       "ip": "123.123.123.124",
       "portal_domain": "1h.mynewveryspecialdomain.com"
     }
  }
}

Response parameters: Returns empty response hash on success:

{ "response_code': 1, "response": [] }

API Client

The API client is a programming library which is written for the purpose of composing API calls, making them, and processing the responses from the server, thus, saving you the need to write the code that does all that. The API client has ready-made functions for all the calls defined above, plus it can be used to compose any new call defined in future without having to be updated.

Here is a sample usage of the API client to activate a new license:

<?php
require_once "PartnerApiClient.php";

$api_client = new PartnerApiClient( 
	'abcde01234',                        //Your API code
	'abcde0123456789abcde0123456789ab'   //Your API key
);

$res = $api_client->add_license( 'Hive', '123.123.123.123' );
if ( !$res )
  var_dump( $api_client->getErrors() );

If the call fails for whatever reason the getErrors() method would return an array containing the errors.

It should be noted that the same call (and any other, as a matter of fact) can be performed via the makeCall() function, which is the "heart" of the API Client class:

<?php
require_once "PartnerApiClient.php";

$api_client = new PartnerApiClient( 
	'abcde01234',                        //Your API code
	'abcde0123456789abcde0123456789ab'   //Your API key
);

$res = $api_client->makeCall( 'add_license',
	array(
		'product' 	=> 'Hive',
		'ip' 		=> '123.123.123.123'
	)
);
if ( !$res )
  var_dump( $api_client->getErrors() );

This way you can call any new method added to the API without having to download an updated client library, containing an explicit declaration of this function.

We currently offer it only for PHP, but we are planning to have it soon in Perl as well. The PHP version can be downloaded from here.

Error codes

This is a list of all errors returned by the current version of the API (1.3.1). Some codes can have more than one possible string description:

Basic/common codes
err_no err_string description
1 Invalid post No POST detected
2 Invalid post data POST "request" parameter not found
3 Invalid request (not JSON) The data posted in the "request" parameter is not properly JSON encoded
4 No payload Missing "payload" property of the JSON object
5 No payload command Missing "command" property of the "payload" object
6 Missing auth info: auth_code Missing "auth_code" property of the JSON object
6 Missing auth info: api_key Missing "api_key" property of the JSON object
7 Invalid auth code: auth_code Auth code not found in records
8 Invalid key The provided key is not correct/present
9 These API credentials have been revoked This API account has been disabled
10 API accessed from invalid IP Invalid IP information passed to server
10 API accessed from unauthorized IP The IP from which the request has not been added to the list of allowed IPs (in Users Area)
11 Command not supported: command The API has been called with unrecognized command
12 Could not load user User record could not be loaded (DB error, please contact us)
13 This user is no longer active The calling user has been suspended
14 Missing param: param_name A parameter which is required for the function being called is missing
15 Invalid param value for param_name ... The provided data value is invalid. Usually an additional explanation follows, specifying the expected format.
22 This user is not associated with your client account The provided sub-user is not associated with your account
add_user specific errors
err_no err_string description
17 A user already exists under this username The provided new username is not unique (it must be unique for the whole system, not only to your account)
20 Could not save new user record Some internal error occurred during the new user activation, please contact us.
update_user specific errors
err_no err_string description
56 Cannot update master user You are providing the username of the master account, rather than one of a sub-user
58 Could not update user record Some internal error occurred during the new user activation, please contact us.
suspend_user specific errors
err_no err_string description
44 Cannot suspend master user suspend_user command can only be called for sub-users
24 Could not suspend user Some internal error occurred during the suspension, please contact us.
unsuspend_user specific errors
err_no err_string description
46 Cannot unsuspend master user unsuspend_user command can only be called for sub-users
26 Could not unsuspend user Some internal error occurred during the unsuspension, please contact us.
add_license specific errors
err_no err_string description
32 This IP is already taken by a different user. You cannot activate any software on that IP. This IP is already taken by a different user. You cannot activate any software on that IP.
34 You already have product license for this IP. You are trying to duplicate an existing license.
36 Failed to activate service for this IP. Some internal error occurred during the activation, please contact us.
remove_license specific errors
err_no err_string description
38 Service record not found for product for ip ip_address Specified license could not be identified - no record for such product on that IP
40 Failed to deactivate service Some internal error occurred during the deactivation, please contact us.
add_portal specific errors
err_no err_string description
48 You already have active portal for this user An attempt is made to activate portal for a sub-user which already has an active portal
50 Failed to activate portal for this IP Some internal error occurred during the deactivation, please contact us.
update_portal specific errors
err_no err_string description
52 You do NOT have active portal for this user An attempt is made to update a non-existing portal (the provided sub-user does not have an active portal).
54 Failed to update portal info for this user Some internal error occurred during the deactivation, please contact us.
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox