Rawstream Platform API

Rawstream Platform API

The Rawstream API allows you to easily integrate Rawstream CloudDNS data into your own applications such as monitoring and dashboards.

You can use the API to retrieve:

Getting started is simple: all you need is a an API Key. To retrieve your API key, log in to the Rawstream Dashboard, then click Settings > Accounts, then scroll to the Rawstream API section.

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&account"
$ {"status-code":200,"status":"OK","data":{"product":"Rawstream DNS Service","quantity":10,"subscription-status-code":3,"subscription-status":"Valid","subscription-ends":"2017-10-18","subscription-days-left":257}}
Prerequisites

You will need a Rawstream account. Sign up here.

API Status

This is the first release of the API. Expect bugs. Please report to support@rawstream.com. Thanks!

Account Status

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&account"

Returns key account information:

List of Networks

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-list"

Returns an array of networks and their properties:

Create a New Network

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-create&name=API-Test-Network&type=dynamic&netip=1.2.3.4&tz=1:0"

Returns an array with:

API to register new networks. Allow 60 seconds for update to propagate. The network will copy and implement the policies of the source network passed. To update the IP of a network with a dynamic IP use the network-update-ip call.

Parameters

Errors

Call returns an error if private IPv4 addresses are passed, or if the IP address is already assigned to another network.

Delete Network

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-delete&netid=NETWORKID"

Deletes the network. Any further requests coming from the network's IP will be dropped. Once a network is deleted, no reporting will be available.

Parameters

Update Network IP

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-update-ip&netid=NETWORKID&newip=1.2.3.4"

Updates the IP of a network with a dynamic public IP address.

By default the IP of the caller is used. You can optionally specify the IP. Only networks that are configured as dynamic networks can be updated. The update fails if the network is not defined as dynamic, or if the IP address is already in use by any other network.

Allow up to 60 seconds for the updated IP to propagate.

Parameters

Copy Network Policy

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-policy-copy&sourcenetid=NETWORKID&netid=NETWORKID"

Copies the policy from the source network to the target network. Networks are identified by their ID. Timezone and name are not copied to target network.

Parameters

Daily Traffic

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-traffic&netid=-1&date=2017-02-02&numdays=2"

Returns number of DNS requests for the indicated days on a daily and per-hour basis.

Parameters

Returns

alt text

Daily Domains

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-domains&netid=-1&date=2017-02-02&numdays=2"

Returns number of DNS requests per domain for the given days.

Parameters

Returns

alt text

Hourly Domains

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-hourly-domains&netid=-1&date=2017-02-02"

Returns number of DNS requests per domain per hour for a specific day.

Parameters

Returns

alt text

Daily Categories

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-categories&netid=-1&date=2017-02-02&numdays=2"

Returns number of DNS requests per domain per hour for a specific day.

Parameters

Returns

alt text

Category IDs

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&categories-table"

Returns the categories and their IDs. The categories are grouped by the major sections: Legal Liability, IT Resources, Security and Productivity

Retrieve Network Policy

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-policy-get&netid=NETWORKID"

Returns the policy for a network. Returns all relevant field except Time-Based related fields.

Parameters

Returns

alt text

Set Network Policy

$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-policy-set&netid=NETWORKID&policy=<JSON ENCODED POLICY>"

Sets a network's policy. Can set all relevant fields except Time-Based ones.

Parameters

If a field is not set in the policy, then either:

Sample Code (Python)

  data['network-policy-set'] = ''
  data['netid'] = NETWORK_ID

  policy = {}
  policy['googlesafesearch'] = 1      # enable google safe search
  policy['safe_youtube'] = 0          # disable Youtube safe search
  policy['allowlist'] = ['test.com', 'test.net']    # set allowed domains
  policy['blocklist'] = ['block.net']               # set blocked domains
  policy['list_mode'] = 0     # 0: allow all categories except those set below,  1: block all categories except those set below
  policy['categories'] = [11, 62, 14]   # Block Pornography, Nudity, and Social Networks
  policy['block_mode'] = 1    # 0: monitor mode, 1: block, shows blockpage
  policy['blockpage'] = """<h2>Access Not Allowed</h2> <p>Testing "[[DOMAINNAME]]"</p>"""   # set message to display when a page is blocked.
  encoded = json.dumps( policy )

  data['policy'] = encoded
  endpoint = RawstreamAPIBase + urllib.urlencode(data)
  rawresponse = urllib2.urlopen( endpoint ).read()

  response = json.loads( rawresponse )
  print response

  if response['status-code'] != 200:
    print 'Error:', response['status-code'], response['status']
    sys.exit()