Release 1.0
SafeDNS JSON-RPC API
JSON-RPC API methods are designed for interaction with the service and making changes intoto the settings.
The API was designed using JSON-RPC protocol and is compatible with the following versions: 1.0 and 2.0. More info is available here: http://www.jsonrpc.org/specification
An example of a CURL request for JSON-RPC 1.0:
curl -X POST https://www.safedns.com/api/json/v1-L-d '{"id":0,"method":"methodName","params":{"param1":"param1"}}'
An example of a CURL request for JSON-RPC 2.0:
curl -X POST https://www.safedns.com/api/json/v2-L-d '{"id":0,"jsonrpc":"2.0","method":"methodName","params":{"param1":"para m1"}}'
Some API methods require basic authentication. In this casecase, authentication details must be sent in the request. Example:
curl -X POST https://www.safedns.com/api/json/v2 -L --user username:password -d '{"id":0,"jsonrpc":"2.0","method":"methodName","params":{"param1":"para m1"}}'
Response format: JSON.
A response example of a successful API call:
{
"jsonrpc": "2.0",
"id": 0,
"result": "result"
}
A method result is included in the “result” key.
In case of an incorrect request the response will be the following:
{
"jsonrpc": "2.0",
"id": 0,
"error": {"code": "code", "name": "name", "message": "message", "data": "data"}
}
Сurrently available API methods:
-
systemInfo - gets information about the system configuration
-
myip - gets the current client’s IP
-
testAuth - user’s authentication
-
register - registers a new user
-
userInfo - gets user information
-
profiles - gets a list of available filtering profiles
-
addProfile - creates a new filtering profile
-
removeProfile - deletes a filtering profile
-
renameProfile - renames a filtering profile
-
categories - gets a list of available filtering categories
-
userFilter - gets a list of filtering categories applied for a user
-
setFilterCat - changes filtering settings
-
domains - gets a list of white- and black-
-
addDomain - adds a domain to the white or black list for a certain filtering profile
-
removeDomain - deletes a domain from a certain filtering profile
-
clearDomains - clears the list of domains for a certain filtering profile
-
updateNic - updates a dynamic IP
-
setWhiteListOnly - enables/disables the “White list only” mode
-
setSafeSearchEnabled - enables/disables “Safe Search mode” for Google and Bing
-
setSafeYoutubeEnabled - enables/disables “Restricted YouTube mode”
-
multiSchedule - gets information on the filtering schedule for a certain profile
-
setSchedule - sets filtering schedule for a certain profile
-
setScheduleEnabled - enables/disables filtering schedule for a certain profile
-
profileScheduleActivity - gets the time left before a change of the filtering profile according to the filtering schedule
-
getProfile - the method includes 3 functions, depending on the parameters:
creates AgentInfo; gets AgentInfo status;
updates AgentInfo profile
-
setProfile - sets a filtering profile for AgentInfo
-
feedback - sends user’s feedback
-
getCategoriesDailyStats - gets daily categories stats of a profile
-
getAdvertising - gets the information on promo
-
getPlans - gets the list of available billing plans
-
getPlan - gets the user’s billing plan
-
getAPCVersion - gets mobile app’s version: minimal supported (that should be forcefully updated) and the current one.
Available methods:
systemInfo
Gets information on the system settings.
Response:
{
"public_dns": <public_dns>, "nxdomain": <nxdomain>, "blockpage": <blockpage>,
"blockpage_token": <blockpage_token>, "blockapi": <blockapi>
}
myip
Gets current client’s IP.
Response:
<ip address>
testAuth
User’s authentication. Mandatory parameters:
-
username - client’s username.
-
password - client’s password.
Response:
<true|false>
register
Registers a new user.
Mandatory parameters:
-
username - client’s username.
-
password - client's password.
Response:
In case of a successful registration:
[true]
If an error occurred:
[false, <error>]
userInfo
Gets user information. Authorization is required.
Response:
{
"plan": {
"name": <plan.name>, "code": <plan.code>, "features": <features>
},
"tz": <timezone_offset / 3600>, "tz_minutes": <timezone_offset / 60>
}
profiles
Gets a list of available filtering profiles. Authorization is required.
Response:
[
{
"name": <name>, "default": <true|false>,
"white_list_only":<true|false>, "token": <token>, "safe_search_enabled": <true|false>, "is_schedule_enabled": <true|false>, "id": <id>
}
]
addProfile
Creates a new filtering profile. Authorization is required.
Mandatory parameter:
-
-
name - profile name
Response:
{
"name": <name>, "default": <true|false>,
"white_list_only": <true|false>, "token": <token>, "safe_search_enabled": <true|false>, "is_schedule_enabled": <true|false>, "id": <id>
}
removeProfile
Deletes a filtering profile. Authorization is required.
Mandatory parameter:
-
profile_id - id of the profile that should be deleted.
Response:
null
renameProfile
Renames a filtering profile. Authorization is required. Mandatory parameters:
-
profile_id - profile id.
-
name - profile name.
Response:
<name>
categories
Gets a list of available filtering categories. Authorization is required.
Response:
[
{
"title": <group1>,
"items": [{"title": <item1>, "id": <id>}]
}
]
userFilter
Gets a list of filtering categories applied for a user. Authorization is required. Mandatory parameter:
-
-
profile_id - profile id.
Response:
[<cat_id1>, <cat_id2>, <cat_id3>]
setFilterCat
Changes filtering settings. Authorization is required. Mandatory parameters:
-
profile_id - profile id.
-
cat - category id.
-
profile_id - profile id.
-
choice - domain type (available options: “black”, “white”, “alias”).
Response:
If the domain type is “black” or “white”
[{"domain":<domain>,"id":<id>}]
If the domain type is “alias”:
[{"domain":<domain>,"id":<id>,"ip":<ip>}]
addDomain
Adds a domain to the white or black list for a certain filtering profile. Authorization is required.
Mandatory parameters:
-
-
profile_id - profile ID.
-
choice - domain type (available options: “black”, “white”, “alias”).
-
domain – domain. Optional parameter:
-
-
ip - IP address, the parameter should be used if the “alias” domain is being
added.
-
comment - adds a comment for a domain.
Response:
removeDomain
Deletes a domain from the white or black list for a certain filtering profile. Authorization is required.
Mandatory parameters:
-
profile_id - profile ID.
-
choice - domain type (available options: “black”, “white”, “alias”).
-
domain – domain.
Response:
null
clearDomains
Clears the list of white-/black- listed domains for a certain filtering profile. Authorization is required.
Mandatory parameters:
-
profile_id - profile ID.
-
choice - domain type (available options: “black”, “white”, “alias”).
Response:
null
updateNic
Updates a dynamic IP. Authorization is required.
Mandatory parameters:
-
-
profile_id - profile ID.
-
profile_id - profile ID.
-
profile_id - profile ID.
-
profile_id - profile ID.
-
flag - boolean value (enable/disable option).
Response:
null
setBlockUnknownEnabled
Enables/disables “Restricted YouTube mode”. Authorization is required. Mandatory parameters:
-
-
profile_id - profile ID.
-
flag - boolean value (enable/disable option).
Response:
null
multiSchedule
Gets information on the filtering schedule for a certain profile. Authorization is required.
Mandatory parameter:
-
profile_id - profile ID.
Response:
[[<offset1>, <true|false>], [<offset2>, <true|false>]]
setSchedule
Sets filtering schedule for a certain profile. Authorization is required Mandatory parameter:
-
profile_id - profile ID.
-
-
segments - a list of segments for scheduling: [[<offset1>, <true|false>], [<offset2>, <true|false>]].
Response:
[true]
setScheduleEnabled
Enables/disables filtering schedule for a certain profile. Authorization is required
Mandatory parameter:
-
profile_id - profile ID.
-
flag - boolean value (enable/disable option).
Response:
<true|false>
profileScheduleActivity
Gets the time left before a change of the filtering profile according to the filtering schedule. Authorization is required
Mandatory parameter:
-
profile_id - profile ID
Response:
[<true|false>, <mins_until_change>]
Note:
If the scheduling is turned off or there are no other states: mins_until_change = -1.
getProfile
This method includes 3 functions, depending on the parameters. Authorization is required.:
-
creates AgentInfo;
-
gets AgentInfo status;
-
updates AgentInfo profile
Mandatory parameters for creating Agent info and getting a profile:
-
uid - ""
-
hostname - hostname.
-
version - version.
-
os_info - information on the OS.
-
address - IP address.
Mandatory parameters for getting the current profile of AgentInfo:
-
uid - uid AgentInfo.
-
hostname - "".
-
version - "".
-
os_info - "".
-
address - "".
Mandatory parameters for updating AgentInfo:
-
uid - uid AgentInfo.
-
hostname - new hostname.
-
version - new version.
-
os_info - new information on the OS.
-
address - new IP address.
Response:
[<uid>, <token>, <profile_id>]
setProfile
Sets a filtering profile for AgentInfo. Authorization is required
Mandatory parameters:
-
uid - uid AgentInfo.
-
profile_id - profile ID.
Response:
null
feedback
Sends user’s feedback. Authorization is required.
Mandatory parameters:
-
title - the subject line.
-
message – user’s message.
Response:
null
getCategoriesDailyStats
Gets daily categories stats of a profile. Authorization is required.
Mandatory parameter:
-
profile_id - profile ID.
-
Optional parameters:
-
lang - response language.
-
categories_list - defines a list of categories. if it’s not set - the result will show all the categories.
Response:
{<category_name>: <value>}
getAdvertising
Gets the information on promo. Authorization is required
Response:
{<strAdvUrl>, <strImageUrl>}
getPlans
Gets the list of available billing plans
Optional parameter:
-
mobile - gets the Plans list, and determines whether to respond with mobile plans only. Boolean value.
Response:
{
'name': <plan name>, 'code': <plan code>,
'isMobile': <is mobile plan>, 'period': <period>, 'trialPeriod': <is trial>, 'price': <price>, 'description': <path>,
}
getPlan
Gets user’s billing plan. Authorization is required.
Response:
{
'name': <plan name>, 'expired': <expired_days>, 'isMobile': <true|false>,
}
getAPCVersion
Gets mobile app’s version: minimal supported (that should be
mandatorymandatorily updated) and the current one.Optional parameter:
-
tag - tag for getting the versions (the value “default” is set by default).
Response:
{
"minimalSupported": <minimum supported version (integer, non-negative number)>,
"current":<current version of the mobile agent (integer, non-negative number)>
}