Skip to main content

8. Rest API

ll interaction with SafeDNS Shield is performed via a REST API, which typically responds on port 8080 from the same IP address that handles user requests. By default, the API only responds to requests from whitelisted IP addresses specified during the server deployment.

Use case

To understand how to work with it, let's consider a specific scenario for initial configuration. This requires sending the following request:

 
  • Type: POST
  • URL: <domain>/init/
  • Data:
{
    "profiles": [
        {
            "profile": {
                "id": 1,
                "page_id": 1
            },
            "cat_ids": [3, 4, 12],
            "app_ids": [1, 12, 93]
        }
    ],
    "blockpages": [
        {
            "id": 1,
            "type": 0
        },
        {
            "id": 2,
            "type": 1
        }
    ],
    "bw_lists": [
       {
            "profile_id": 1,
            "type": "deny",
            "domains": [
                "example1.com",
                "example2.com",
                "example3.com"
            ]
        }
    ],
    "nets": [
        {
            "ip": "100.100.100.100",
            "profile_id": 1,
            "prefix_len": 32
        },
        {
            "ip": "100.110.110.0",
            "profile_id": 1,
            "prefix_len": 24
        },
        {
            "ip": "100.120.0.0",
            "profile_id": 1,
            "prefix_len": 16
        }
    ],
    "nets6": [],
    "napts": []
}

In this init file (in sequence), we configure the SafeDNS On-Prem as follows:

  • Create a single filtering profile with id=1 and a blocking page with id=1 [profiles → profile].
  • In this profile’s settings, specify three blocked categories (in this example: malware, phishing, and botnets) [profiles → cat_ids].
  • Specify three blocked AppBlocker categories (in this example: Slack, AnyDesk, Netflix) [profiles → app_ids].
  • Create two blocking pages of different types (type 0 - displays the blocked domain, type 1 - without showing the blocked domain) [blockpages].
  • Add three domains to the blacklist for the filtering profile with id=1 [bw_lists].
  • Assign IP addresses to the filtering profile with id=1, so requests from these IPs are filtered according to the profile’s policy (in this example: 1 specific IP and 2 subnets with /16 and /24 masks) [nets].
  • [nets6] (same as nets but for IPv6) and [napts] (user identification behind NAT via port) are not filled in this example, but must be sent (empty) to initiate the creation of the initial configuration.

Once this request is sent, and a successful response with status code 204 is received, the initial configuration is complete, and all DNS traffic to this server will be processed according to the specified rules.


Modifying Filtering Categories

Let’s now consider typical use cases for changing or updating filtering settings. For instance, if you want to modify the categories being filtered, you’ll need to update the entire list of categories for the relevant profile. Based on the example above, we had a single profile created with two categories. Suppose we want to add three more categories (Cryptojacking, DGA, and Ransomware). To do this, you need to send the following request:

 
  • Type: PATCH
  • URL: <domain>/profiles/1/
  • Data:
{
  "cat_ids": [3, 4, 12, 66, 70, 71],
  "app_ids": [1, 12, 93],
  "profile": {
    "page_id": 1
  }
}

That is, we specified the profile ID directly in the URL, and in the request body, we provided the updated list of categories (the previous 3 plus the new 3), while keeping the same AppBlocker categories and blockpage as before.


Adding an Address to the Allowlist

Now, let’s consider a scenario where a specific domain from the blocked list needs to be added to the whitelist to bypass category-based blocking. To achieve this, send the following request:

 
  • Type: POST
  • URL: <domain>/profile/1/bw_list
  • Data:
{
  "type": "allow",
  "domain": "example4.com"
}

Thus, for the filtering profile with id=1, we added the domain to the allowlist, giving it priority over category-based blocking.


Adding Domains to the Denylist

Now, suppose we need to block certain domains that are not part of the filtered categories. To do this, we’ll add them to the denylist using a batch method:

 

Type: POST
URL: <domain>/profile/1/bw_list/batch
Data:

{
  "type": "deny",
  "domains": ["example5.com", "example6.com", "example7.com", "example8.com", "example9.com"]
}
Adding a New Network (or IP) for Filtering:
 

Type: POST
URL: <domain>/net/
Data:

{
    "ip": "100.100.100.101",
    "profile_id": 1,
    "prefix_len": 32
}

Thus, we added a new IP to our filtering profile. In this case, we specified a network prefix of /32. If we needed to specify an entire subnet, we could have sent, for example:

{
    "ip": "100.100.101.0",
    "profile_id": 1,
    "prefix_len": 24
}

Removing an IP from the List

Adding a new network (or IP) for filtering:

  • Type: DELETE
  • URL: <domain>/net/1684300901
  • Data: None

This request has no body. The only requirement is to provide the IP address in decimal format within the URL. You must use the exact IP previously submitted (without the mask), e.g., 100.100.100.101 or 100.100.101.0 for the earlier examples. To convert an IP address to decimal format, you can use a converter like [this one].


Modifying the Filtering Profile for a Specific IP
 

Type: PATCH
URL: <domain>/net/1684301056
Data:

{
    "ip": "100.100.101.0",
    "profile_id": 2,
    "prefix_len": 24
}

In this case, we addressed the record for 100.100.101.0 (in decimal format in the URL) and changed the profile from id=1 to id=2. To modify the prefix, for instance, from /24 to /16, we would need to delete this record and add a new one with the appropriate prefix, replacing 100.100.101.0 with 100.100.0.0.


Creating a New Filtering Profile

In the example above, we changed the filtering profile for a specific IP. However, such a profile hasn’t been created yet. Here’s how you can create it:

 
  • Type: POST
  • URL: <domain>/profiles/
  • Data: 
    {
    "profile": {
        "id": 2,
        "page_id": 1
    },
    "cat_ids": [3, 4, 12, 66, 70, 71, 13],
    "app_ids": [1, 12, 93]
}

Thus, we created a filtering profile with id=2, specified the same type of blocking page, and assigned the same categories and AppBlocker settings as in the first profile, adding a new category — "Adult Related".


Complete API Methods Description

User data methods

 
  • Initialize user data database (batch data creation):
    • Type: POST
    • URL: <domain>/init/
    • Data: 
      {
    'profiles': [
        {
            'cat_ids': [<cat_id>,],
            'app_ids': [<app_id>,],
            'profile': {
                'page_id': <page_id>,
                'id': <id>
            }
        }, ...
    ],
    'nets': [{'ip': <ipv4>, 'profile_id': <profile_id>, 'prefix_len': <prefix_len4>}, ...],
    'nets6': [{'ip': <ipv6>, 'profile_id': <profile_id>, 'prefix_len': <prefix_len6>}, ...],
    'blockpages': [{'id': <page_id>, 'type': <blockpage_type>}, ...],
    'napts': [
        {
            'ip': <ipv4>,
            "profile_id": <profile_id>,
            "lower_port_bound": <lower_port_bound>,
            "upper_port_bound": <upper_port_bound>
        },
    ]
}
    • Result: 204 No body

Profile methods

 
  • Fetch all profiles:
    • Type: GET
    • URL: <domain>/profiles
    • Result: 200 OK
  • Add a profile:
    • Type: POST
    • URL: <domain>/profiles
    • Data: 
      {
    "profile": {
        "id": int,
        "page_id": int
    },
    "cat_ids": [int, ],
    "app_ids": [int, ],
}
    • Result: 201 Created
  • Fetch a specific profile:
    • Type: GET
    • URL: <domain>/profiles/<id>
    • Result: 200 OK
  • Update a specific profile:
    • Type: PATCH
    • URL: <domain>/profiles
    • Data: 
      {
  "app_ids": [int, ],
  "cat_ids": [int, ],
  "profile": {
    "plan_id": int,
    "provider_id": int,
    "white_list_only": bool,
    "hide_block_reason": bool,
    "empty_dns_answer": bool,
    "page_id": int,
    "tls": bool
  }
}
    • Result: 200 OK

Blockpage methods

 
  • Get all blockpages:
    • Type: GET
    • URL: <domain>/blockpage
    • Result: 200 OK
  • Create a blockpage:
    • Type: POST
    • URL: <domain>/blockpage
    • Data: 
      {
  "type": int,
  "id": int
}
    • Result: 200 OK
  • Get a specific blockpage:
    • Type: GET
    • URL: <domain>/blockpage/<page_id>
    • Result: 200 OK
  • Update a blockpage:
    • Type: PATCH
    • URL: <domain>/blockpage/<page_id>
    • Data: 
      {
  "type": int
}
    • Result: 200 OK
  • Delete a blockpage:
    • Type: GET
    • URL: <domain>/blockpage/<page_id>
    • Result: 204 No Content, no body

Lists methods

 
  • Create an allow- or denylist:
    • Type: POST
    • URL: <domain>/profile/<profile_id>/bw_list
    • Data: 
      {
  "type": "string", //"allow" or "deny" only
  "domains": ["string", "string", ]
}
    • Result: 201 Created
  • Create an allow- or denylist with multiple entries:
    • Type: POST
    • URL: <domain>/profile/<profile_id>/bw_list/batch
    • Data: 
      {
  "type": "string", //"allow" or "deny" only
  "domains": ["string", "string", ]
}
    • Result: 201 Created
  • Update a domain in an allow- or denylist:
    • Type: PATCH
    • URL: <domain>/profile/<profile_id>/bw_list/<domain>
    • Data: 
      {
  "type": "string", //"allow" or "deny" only
  "domain": "string",
  "profile_id": int
}
    • Result: 200 OK
  • Delete a domain from an allow- or denylist:
    • Type: DELETE
    • URL: <domain>/profile/<profile_id>/bw_list/<domain>
    • Result: 204 No Content, no body

IPv4 network methods

 
  • Create an IPv4 address entry:
    • Type: POST
    • URL: <domain>/net
    • Data: 
      {
  "ip": "string", //IPv4 address in canonical form
  "profile_id": int,
  "prefix_len": int
}
    • Result: 201 Created
  • Get an IPv4 address entry:
    • Type: GET
    • URL: <domain>/net/<int_ip>
    • Result: 200 OK
  • Update an IPv4 address entry:
    • Type: PATCH
    • URL: <domain>/net/<int_ip>
    • Data: 
      {
  "ip": "string", //IPv4 address in canonical form
  "profile_id": int,
  "prefix_len": int
}
    • Result: 200 OK
  • Delete an IPv4 address:
    • Type: DELETE
    • URL: <domain>/net/<int_ip>
    • Result: 204 No Content, no body

IPv6 network methods

 
  • Create an IPv6 address entry:
    • Type: POST
    • URL: <domain>/net6
    • Data: 
      {
  "ip": "string", //IPv6 address in canonical form
  "prefix_len": int,
  "profile_id": int
}
    • Result: 201 Created
  • Get an IPv6 address entry:
    • Type: GET
    • URL: <domain>/net6/<ipv6>
    • Result: Dictionary with IPv6 and profile_id data
  • Update an IPv6 address entry:
    • Type: PATCH
    • URL: <domain>/net6/<ipv6>
    • Data: 
      {
  "ip": "string", //IPv6 address in canonical form
  "prefix_len": int,
  "profile_id": int
}
    • Result: 200 OK
  • Delete an IPv6 address:
    • Type: DELETE
    • URL: <domain>/net6/<ipv6>
    • Result: 204 No Content, no body

IPv4 NAT methods

 
  • Create an IPv4 NAT entry:
    • Type: POST
    • URL: <domain>/napt/
    • Data: 
      {
  "ip": "string", //IPv4 address in canonical form
  "lower_port_bound": int,
  "upper_port_bound": int,
  "profile_id": int
}
    • Result: 201 Created
  • Create multiple IPv4 NAT entries:
    • Type: POST
    • URL: <domain>/napt/batch
    • Data: 
      [
  {
  	"ip": "string", //IPv4 address in canonical form
  	"lower_port_bound": int,
  	"upper_port_bound": int,
  	"profile_id": int
  },
  
]
    • Result: 201 Created
  • Get all IPv4 NAT entries by IP:
    • Type: GET
    • URL: <domain>/napt/<int_ip>
    • Result: 200 OK
  • Get a specific IPv4 NAT entry:
    • Type: GET
    • URL: <domain>/napt/<int_ip>/<lower_port_bound>/<upper_port_bound>
    • Result: 200 OK
  • Update an IPv4 NAT entry:
    • Type: PATCH
    • URL: <domain>/napt/<int_ip>/<lower_port_bound>/<upper_port_bound>
    • Data: 
      {
  "ip": "string", //IPv4 address in canonical form
  "lower_port_bound": int,
  "upper_port_bound": int,
  "profile_id": int
}
    • Result: 200 OK
  • Delete an IPv4 NAT entry:
    • Type: DELETE
    • URL: <domain>/napt/<int_ip>/<lower_port_bound>/<upper_port_bound>
    • Result: 204 No Content, no body
  • Delete multiple IPv4 NAT entries:
    • Type: DELETE
    • URL: <domain>/napt/batch
    • Data: 
      [
  {
  	"ip": "string", //IPv4 address in canonical form
  	"lower_port_bound": int,
  	"upper_port_bound": int,
  	"profile_id": int
  },
  
]
    • Result: 204 No Content, no body

AppBlocker methods

  • Get a list of all available AppBlocker categories:
    • Type: GET
    • URL: <domain>/app_aware/application/
    • Result: 200 OK

Back to top