API Documentation

It is possible to submit results directly to the competition via the API. The API is available at https://cosc417dns.com/api/raw and it requires that you send data as a post request. Each request requires your API key, a QNAME, a QTYPE, and a resolver IP address. When successful, the API will simply return the amplification ratio that your request achieved. If an error is encountered, it will return an HTTP error code as well as a short text message describing the error.

This server has rate-limiting enabled. The server will not allow more than 1 request per second per client. If this is exceeded, an HTTP 503 (Service Unavailable) error will be returned. Use the sleep() function in your code to add at least a one-second delay between requests, preferably more.

Here is a brief example Python application that submits a result to the server:

from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
from time import sleep

# The URL to the raw API page
api_url = 'http://cosc417dns.com/api/raw'

# POST data to send
post_data = {
    'apikey': '123abc456def',   # Your API key
    'qname': 'google.com',      # The qname you're querying
    'qtype': 'A',               # The DNS record type, can be text ('A') or numeric ('1')
    'resolver': '1.1.1.1'       # The resolver IP address, must be IPv4
}

# Build the request
request = Request(api_url, urlencode(post_data).encode())

# Try sending it
try:
    # Make sure you don't hit the rate limit
    sleep(1)
    with urlopen(request) as response:
        # Decode the amplification ratio and parse it as a float
        result = float(response.read().decode())
        print(result)

# If something goes wrong, print out the error message sent by the server
except HTTPError as e:
    print(e.fp.read().decode())