Skip to main content

Rest API overview

llAll interactionadministration withand configuration of SafeDNS Shield is performed viathrough athe REST API,API. whichThe typicallyAPI respondslistens on port 8080 fromof the same IP address that handles userDNS requests.queries. By default, theaccess APIis only respondsrestricted to requestsa fromset of whitelisted IP addresses specified during the server deployment.

Use

Initial case

Configuration Example

ToThe understandfollowing howexample todemonstrates work with it, let's consider a specific scenario forthe initial configuration.configuration Thisworkflow. requires sendingSend 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": []
}

InThe thisinitialization initquery file (in sequence), we configuredefines the full configuration applied to SafeDNS On-PremShield. asThe follows:following settings are processed in sequence:

    1. Create a

      Filtering singleprofile and block page – A filtering profile with id=1(ID=1) and a blockingblock page with(ID=1) id=1are [profilescreated.

      → profile].
    2. In this

      Blocked profile’scategories settings,– specifyThree threeDNS categories are blocked categoriesfor (inthe this example:profile: malware, phishing, and botnets)botnets.

      [profiles → cat_ids].
    3. Specify three

      Blocked blockedapplications – Three AppBlocker categories (inare this example:blocked: Slack, AnyDesk, Netflix)and [profilesNetflix.

      → app_ids].
    4. Create two

      Block blockingpages – Two block pages of different types (typeare created:

      • Type 0 -– displays the blocked domain,domain typename.

    Type 1 -– withoutdoes showingnot display the blocked domain)domain [blockpages].
    name.

    Add three

    Blacklist – Three domains are added to the blacklist for the filtering profile with1.

    id=1 [bw_lists].
    Assign

    IP assignment – The profile is assigned one specific IP addressesaddress toand thetwo filteringsubnets profile(/16 withand id=1,/24). soDNS requests from these IPssources are filtered according to the profile’s policypolicy.

    (in this example: 1 specific IP

    IPv6 and 2NAT‑port subnetsidentification with– /16The and /24 masks) [nets].

    [nets6]nets6 (same as nets but for IPv6) and [napts]napts (user identification behind NAT viaport‑based port)identification) sections are not filled in this example,included but left empty. These fields must be sentpresent (empty)in the request even if not used, to initiatetrigger the creation of the initial configuration.

    Once thisthe request is sent,sent and a successful response with(HTTP status code 204) is received, the initial configuration is complete,complete. andAll allsubsequent DNS traffic toprocessed thisby the server willis be processedhandled 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 toTo modify the filtering categories beingfor filtered,an you’llexisting needprofile, toyou must update the entire list of categories forassigned to that profile. Adding new categories requires sending the relevantfull profile.set Based(both oncurrent theand examplenew above,categories) we hadin a single profilerequest.

    For example, the initial configuration created profile id=1 with twothree categories.blocked Supposecategories: wemalware, wantphishing, toand botnets. To add three more categories (Cryptojacking, DGA, and Ransomware). To do this, you need to sendRansomware, the followingrequest request:must include all six categories:

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

    ThatIn is,this we specifiedrequest, the profile ID is specified directly in the URL,URL. and in theThe request body,body we providedcontains the updated list of categories (theoriginal previousthree 3and plusthree the new 3),new) while keeping the same AppBlocker categories and blockpageblock aspage before.

    remain


    unchanged.

    Adding ana AddressDomain to the Allowlist

    Now,To let’s consider a scenario whereexempt a specific domain from thecategory-based blockedblocking, listadd needs to be addedit to the whitelistallowlist toof bypassthe category-basedrelevant blocking.filtering Toprofile. achieveFor this,profile id=1, send the following request:

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

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


    Adding Domains to the Denylist

    Now, suppose we need toTo block certainspecific domains that are not partcovered ofby the filteredconfigured categories. To do this, we’llcategories, add them directly to the denylist usingfor the filtering profile. The following request adds domains in a batch method:operation for profile id=1:

     

      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)IP Address for Filtering:Filtering

      To assign a new IP address or subnet to a filtering profile, send the following request. The example adds a single IP address by specifying a /32 network prefix for profile id=1:

       

        Type: POST
        URL: <domain>/net/
         Data: 
        {
    "ip": "100.100.100.101",
    "profile_id": 1,
    "prefix_len": 32
}

        Thus,To we added a new IP to our filtering profile. In this case, we specified a network prefix of /32. If we needed to specifyadd an entire subnet, weadjust couldthe haveprefix sent,length foraccordingly. example:For instance, a /24 subnet would be specified as:

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

        Removing an IP Address from Filtering

        To remove a previously assigned IP address or subnet from a filtering profile, send the Listfollowing

        Adding a new network (or IP) for filtering:request:

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

        This request has no body. The only requirement is to provide the IP address must be provided in decimal format withinin the URL. You must useUse the exact IPaddress previouslyoriginally submittedsubmitted, (without the mask),mask e.g.,- for example, 100.100.100.101 or 100.100.101.0 forfrom the earlier examples. ToYou can convert an IP address to decimal format,format you can useusing a convertertool like [this one].


        Modifying the Filtering Profile for a Specific IP

        To change the filtering profile assigned to an existing IP address or subnet, send the following request. The IP address must be provided in decimal format in the URL. This example reassigns the address 100.100.101.0 (originally a /24 subnet) from profile id=1 to profile id=2:

         

          Type: PATCH
          URL: <domain>/net/1684301056
           Data: 
          {
    "ip": "100.100.101.0",
    "profile_id": 2,
    "prefix_len": 24
}

          InTo this case, we addressedchange the recordnetwork prefix (for 100.100.101.0example, (infrom decimal/24 formatto in/16), you must delete 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 thisexisting record and add a new one with the appropriatecorrect prefix,network replacingaddress. In this case, you would delete 100.100.101.0 and add 100.100.0.0 with 100.100.0.0.

          the 


          /16 prefix.

          Creating a New Filtering Profile

          InBefore thean exampleIP above,can webe changedreassigned theto a different profile, that profile must exist. The following request creates a new filtering profile for a specific IP. However, such a profile hasn’t been created yet. Here’s how you can create it:profile:

           
          • 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]
}

          This

          Thus, we created a filteringcreates profile 

          id=2, configured with id=2, specified the same block page type of blocking page, and assigned the same categories and AppBlocker settings as inprofile id=1, with the firstaddition profile,of adding a new category —the "Adult Related".


          category.

          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