<.
##### API Status
This is the first release of the API. Expect bugs. Please report to support@rawstream.com. Thanks!
- API Version: *0.2*
- API Last Update: *2018-04-16*
- Document Last Update: *2018-05-01*
### Account Status
```sh
$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&account"
```
Returns key account information:
- subscription status code
- number of seats
- date subscription expiration
- number of days left to subscription expiration
### List of Networks
```sh
$ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-list"
```
Returns an array of networks and their properties:
- network ID
- name
- IP address
- timezone offset in hours
- whether the network is enabled (1) or not (0)
- Google SafeSearch enabled (1) or not (0)
- Youtabe SafeSearch enabled (1) or not (0)
### Create a New Network
```sh
$ 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:
- network ID
- IP address
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__
- name: name to be assigned to new network. Maximum length: 40 characters.
- enumerated type - *static* or *dynamic*: *static* for networks with a static public IP. *dynamic* for networks with dynamic public IPs.
- sourcenetname: Name of network to source policy and block page from.
- netip: Optional. IPv4 IP address. If empty, uses the IP of the caller.
- dynuser: Optional. Dynamic username if using the Rawstream DynIP agent to update the IP of the network.
- dynpasswd: Optional. Dynamic password if using the Rawstream DynIP agent to update the IP of the network.
- tz: Optional. Timezone of network. Format is "hour:0" and "-hour:0". Ex: -3:0. Default is UTC: 0:0
__Errors__
Call returns an error if private IPv4 addresses are passed, or if the IP address is already assigned to another network.
### Delete Network
```sh
$ 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__
- netid: network ID. -1 is not valid.
### Update Network IP
```sh
$ 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__
- netid: network ID. -1 is not valid.
- newip: Network's new IP
### Copy Network Policy
```sh
$ 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__
- sourcenetid: network ID. -1 is not valid.
- netid: network ID. -1 is not valid.
### Daily Traffic
```sh
$ 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__
- netid: -1 for aggregate network data, or network ID
- date: yyyy-mm-dd format. Optional. Default is today
- numdays: Optional. Default is 1. Max is 7
__Returns__
![alt text][network-daily-traffic]
[network-daily-traffic]: http://data.rawstream.com/docs/images/network-daily-traffic.png
### Daily Domains
```sh
$ 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__
- netid: -1 for aggregate network data, or network ID
- date: yyyy-mm-dd format. Optional. Default is today
- numdays: Optional. Default is 1. Max is 7
- filtered: Optional. If set returns only the filtered domains.
__Returns__
![alt text][network-daily-domains]
[network-daily-domains]: http://data.rawstream.com/docs/images/network-daily-domains.png
### Hourly Domains
```sh
$ 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__
- netid: -1 for aggregate network data, or network ID
- date: yyyy-mm-dd format. Optional. Default is today
- numdays: Optional. Default is 1. Max is 7
- filtered: Optional. If set returns only the filtered domains.
__Returns__
![alt text][network-hourly-domains]
[network-hourly-domains]: http://data.rawstream.com/docs/images/network-hourly-domains.png
### Daily Categories
```sh
$ 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__
- netid: -1 for aggregate network data, or network ID
- date: yyyy-mm-dd format. Optional. Default is today
- numdays: Optional. Default is 1. Max is 7
__Returns__
![alt text][network-daily-categories]
[network-daily-categories]: http://data.rawstream.com/docs/images/network-daily-categories.png
### Category IDs
```sh
$ 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
```sh
$ 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__
- netid: network ID
__Returns__
![alt text][network-get-policy]
[network-get-policy]: http://data.rawstream.com/docs/images/network-get-policy.png
- list_mode: 0 - allow all categories except listed. 1 - block all categories except listed
- block_mode: 0 - monitor mode. 1 - block, shows blockpage
### Set Network Policy
```sh
$ 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__
- netid: network ID
- policy: JSON encoded policy
If a field is not set in the policy, then either:
- existing value is kept if the network already has a policy
- default value for that field is kept. Usually default value is either field is empty, or zero'd out.
__Sample Code (Python)__
```sh
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()
```
]]>