Responses¶
API Responses¶
Syntax Checker¶
{
"checker_type": "SYNTAX",
"idna_subject": "example.com",
"params": null,
"status": "VALID",
"status_source": "SYNTAX",
"subject": "example.com",
"tested_at": "2021-03-09T17:43:24.477977"
}
Availability Checker¶
{
"checker_type": "AVAILABILITY",
"dns_lookup": {
"NS": [
"a.iana-servers.net.",
"b.iana-servers.net."
]
},
"dns_lookup_record": {
"dns_name": "example.com.",
"follow_nameserver_order": true,
"nameserver": "9.9.9.9",
"port": 53,
"preferred_protocol": "UDP",
"query_record_type": "NS",
"query_timeout": 5.0,
"response": [
"a.iana-servers.net.",
"b.iana-servers.net."
],
"subject": "example.com",
"used_protocol": "UDP"
},
"domain_syntax": true,
"expiration_date": null,
"http_status_code": null,
"idna_subject": "example.com",
"ip_syntax": false,
"ipv4_range_syntax": false,
"ipv4_syntax": false,
"ipv6_range_syntax": false,
"ipv6_syntax": false,
"netinfo": null,
"params": {
"do_syntax_check_first": false,
"use_dns_lookup": true,
"use_extra_rules": true,
"use_http_code_lookup": true,
"use_netinfo_lookup": true,
"use_reputation_lookup": false,
"use_whois_db": true,
"use_whois_lookup": false,
"use_collection": false
},
"second_level_domain_syntax": true,
"status": "ACTIVE",
"status_after_extra_rules": null,
"status_before_extra_rules": null,
"status_source": "DNSLOOKUP",
"status_source_after_extra_rules": null,
"status_source_before_extra_rules": null,
"subdomain_syntax": false,
"subject": "example.com",
"tested_at": "2021-03-09T17:42:15.771647",
"url_syntax": false,
"whois_lookup_record": {
"expiration_date": null,
"port": 43,
"query_timeout": 5.0,
"record": null,
"server": null,
"subject": "example.com"
},
"whois_record": null
}
Reputation Checker¶
{
"checker_type": "REPUTATION",
"dns_lookup": [
"93.184.216.34"
],
"dns_lookup_record": {
"dns_name": "example.com.",
"follow_nameserver_order": true,
"nameserver": "9.9.9.9",
"port": 53,
"preferred_protocol": "UDP",
"query_record_type": "A",
"query_timeout": 5.0,
"response": [
"93.184.216.34"
],
"subject": "example.com",
"used_protocol": "UDP"
},
"domain_syntax": true,
"idna_subject": "example.com",
"ip_syntax": false,
"ipv4_range_syntax": false,
"ipv4_syntax": false,
"ipv6_range_syntax": false,
"ipv6_syntax": false,
"params": {
"do_syntax_check_first": false,
"use_collection": false
},
"second_level_domain_syntax": true,
"status": "SANE",
"status_source": "REPUTATION",
"subdomain_syntax": false,
"subject": "example.com",
"tested_at": "2021-03-09T17:44:02.908452",
"url_syntax": false
}
API Responses (explained)¶
In this page, we intend to explain the most useful parts of the API responses.
checker_type
¶
The checker type. It describes the checker which was used to provide the given response.
It should be one of the following:
SYNTAX
AVAILABILITY
REPUTATION
idna_subject
¶
The IDNA formatted subject. It is the subject that is internally exposed the all supported testing methods.
You should consider this as the subject and consider the subject
key as
a placeholder of what was given by you.
params
¶
The parameters. It describes the parameter applied to the checker. In most case, if you are using the Python API, you should be able to control most of them through the class constructor or their property setters with the same name.
Syntax Checker¶
As of now, there is no known parameters.
Availability Checker¶
With the availability checker, the following is provided.
{
"do_syntax_check_first": false,
"use_dns_lookup": true,
"use_extra_rules": true,
"use_http_code_lookup": true,
"use_netinfo_lookup": true,
"use_reputation_lookup": false,
"use_whois_db": true,
"use_whois_lookup": false,
"use_collection": false
}
do_syntax_check_first
¶
This parameter lets the checker know that it has to do a syntax check before starting an extensive test. Meaning that the status strongly depends on the caught syntax.
use_dns_lookup
¶
This parameter lets the checker know that it is allowed to perform some DNS lookup to determine the status of the given subject.
use_extra_rules
¶
This parameter lets the checker know that it is allowed to check against our own sets of SPECIAL rules in order to escalate or deescalate the status of the given subject.
use_http_code_lookup
¶
This parameter lets the checker know that it is allowed to gather and use the HTTP status code of the given subject to determine its status.
use_netinfo_lookup
¶
This parameter lets the checker know that it is allowed to perform a network information lookup to determine the status of the given subject.
use_reputation_lookup
¶
This parameter lets the checker know that is allowed to perform a reputation lookup to determine the status of the given subject.
use_whois_db
¶
This parameter lets the checker know that it is allowed to look at the WHOIS local WHOIS database before even trying to perform a WHOIS lookup to determine the status of the given subject.
Warning
If the use_whois_lookup
parameter is deactivated, this parameter is
ignored.
use_whois_lookup
¶
This parameter lets the checker know that is it allowed to perform a WHOIS lookup to determine the status of the given subject.
use_collection
¶
This parameter lets the checker know that it is allowed to perform a lookup into the collection API before starting an extensive local test.
Reputation Checker¶
With the availability checker, the following is provided.
{
"do_syntax_check_first": false,
"use_collection": false
}
do_syntax_check_first
¶
This parameter lets the checker know that it has to do a syntax check before starting an extensive test. Meaning that the status strongly depends on the caught syntax.
use_collection
¶
This parameter lets the checker know that it is allowed to perform a lookup into the collection API before starting an extensive local test.
status
¶
The status. It describes the final status gathered by the checker.
Availability Checker¶
With the availability checker, it may be one of the following:
ACTIVE
INACTIVE
INVALID
status_after_extra_rules
¶
The status after our extra rules lookup. It describes the status after the lookup against our own sets of rules.
If no rules were matched, null
is provided.
Warning
Beware, this is only provided by the availability checker.
status_before_extra_rules
¶
The status before our extra rules lookup. It describes the status before the lookup against our own sets of rules. In other words, it is the status provided by our standard status lookup strategy.
If no rules were matched, null
is provided.
Warning
Beware, this is only provided by the availability checker.
status_source
¶
The status source. It describes the test method that led to the given status.
It should be one of the following:
SYNTAX
WHOIS
DNSLOOKUP
NETINFO
HTTP CODE
SPECIAL
(extra rules)COLLECTION
status_source_after_extra_rules
¶
The status source after our extra rules lookup. It describes the status source after the lookup against our own sets of rules.
It should be SPECIAL
.
If no rules were matched, null
is provided.
Warning
Beware, this is only provided by the availability checker.
status_source_before_extra_rules
¶
The status source before our extra rules lookup. It describes the status source before the lookup against our own sets of rules.
In other words, it is the status source provided by our standard status lookup strategy.
It should be one of the following:
SYNTAX
WHOIS
DNSLOOKUP
NETINFO
HTTP CODE
COLLECTION
If no rules were matched, null
is provided.
Warning
Beware, this is only provided by the availability checker.
subject
¶
The subject. It describes the subject that was given by you.
tested_at
¶
The test date. It may not be useful to everyone, but it describes the date and time of the generation of the given output.
dns_lookup
¶
The DNS lookup summary. It describes the summary of the DNS Lookup that was performed.
Syntax Checker¶
Non-existent.
Availability Checker¶
With the availability checker, the following format (or null
) is provided:
{
"QUERY TYPE": [
"string",
"string"
]
}
Where QUERY TYPE
is one of the following:
NS
A
AAAA
CNAME
DNAME
Reputation Checker¶
With the reputation checker, the following format (or null
) is provided:
[
"string",
"string"
]
It is just a simple list of IPs that we check against. When the given
subject is an IPv4, null
is provided.
dns_lookup_record
¶
The DNS lookup record. It describes the latest performed DNS lookup record.
Syntax Checker¶
Non-existent.
Availability and Reputation Checker¶
With the availability or reputation checker, the following is provided.
{
"dns_name": "example.com.",
"follow_nameserver_order": true,
"nameserver": "9.9.9.9",
"port": 53,
"preferred_protocol": "UDP",
"query_record_type": "NS",
"query_timeout": 5.0,
"response": [
"a.iana-servers.net.",
"b.iana-servers.net."
],
"subject": "example.com",
"used_protocol": "UDP"
}
dns_name
¶
The DNS name. It describes the DNS name that was queried.
follow_nameserver_order
¶
It describes if we followed the nameserver order.
nameserver
¶
The nameserver. It describes the nameserver that was queried last.
port
¶
The port. It describes the port that was used to communicate with the nameserver.
query_record_type
¶
The query record type. It describes the record type that was queried last.
query_timeout
¶
The query timeout. It describes the query timeout that was used to perform the query.
response
¶
The response. It describes a list of domains or IPs given by the nameserver as response.
subject
¶
The subject. It describes the subject that was given to the query tool.
used_protocol
¶
The used protocol. It describes the used protocol.
It should be one of the following:
UDP
(default)TCP
HTTPS
TLS
domain_syntax
¶
The domain syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is a 2nd level
domain or a subdomain.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
expiration_date
¶
The expiration date. It describes the expiration date of the given subject as extracted from the WHOIS record.
If none is found, null
will be provided.
Warning
Beware, this is only provided by the availability checker.
http_status_code
¶
The HTTP status code. It describes the HTTP status code which was discovered.
If none is found, null
or 0
will be provided.
Warning
Beware, this is only provided by the availability checker.
ip_syntax
¶
The IP syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is an IPv4 or
an IPv6 (range excluded).
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
ipv4_range_syntax
¶
The IPv4 range syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is an IPv4
range.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
ipv4_syntax
¶
The IPv4 syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is an IPv4
(range excluded).
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
ipv6_range_syntax
¶
The IPv6 range syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is an IPv6
range.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
ipv6_syntax
¶
The IPv6 syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is an IPv6
(range excluded).
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
second_level_domain_syntax
¶
The 2nd level domain syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is a 2nd level
domain.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
subdomain_syntax
¶
The subdomain syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is a subdomain.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
url_syntax
¶
The subdomain syntax. It describes through a boolean the state of the given subject.
In other words: true
is provided when the given subject is a URL.
Warning
This key may give you a null
if nothing was performed (yet).
Warning
Beware, this is only provided by the availability and reputation checkers.
netinfo
¶
The network information summary. It describes the summary of the network information lookup.
Syntax Checker¶
Non-existent.
Availability Checker¶
With the availability checker, the following format (or null
) is
provided:
[
"string",
"string"
]
It is just a simple list of IPs or domains that were found. Otherwise,
null
will be supplied.
Reputation Checker¶
Non-existent.
whois_lookup_record
¶
The WHOIS lookup record. It describes the latest performed WHOIS lookup record.
Syntax Checker¶
Non-existent.
Availability Checker¶
With the availability checker, the following is provided.
{
"expiration_date": null,
"port": 43,
"query_timeout": 5.0,
"record": null,
"server": null,
"subject": "example.com"
}
expiration_date
¶
The expiration date. It describes the extracted expiration date.
It should be a string if the format 09-oct-1970 or null
otherwise.
port
¶
The port. It describes the port used to communicate with the WHOIS server.
query_timeout
¶
The query timeout. It describes the query timeout that was applied during the query.
record
¶
The WHOIS record. It describes the record or response of the WHOIS server.
subject
¶
The subject. It describes the subject which was queried.
Reputation Checker¶
Non-existent.
whois_lookup
¶
The WHOIS record. It describes the WHOIS record as given by the (root) WHOIS server.
Warning
Beware, this is only provided by the availability checker.
CLI Responses¶
From the CLI, there is a lot less information available to the end-user. This patch intend to shortly preset each column of the CLI stdout outputs.
Subject¶
The subject. It describes the given or decoded subject after conversion to IDNA.
Status¶
The status. It describes the official status of the tested subject.
Source¶
The status source. It describes the method that let to the given status.
Expiration Date¶
The expiration date. It describes the expiration date extracted from the WHOIS
record - if found. Otherwise, Unknown
is supplied.
HTTP Code¶
The HTTP status code. It describes the HTTP status code - if found. Otherwise,
Unknown
is supplied.
Checker¶
The checker. It describes the checker used to gather the status.