Domain Directory Traffic Summary Report - POST /api/report/dirflow
Get the traffic volume in megabytes and peak bandwidth at five minute granularity for one or more directories of specific domains. Within the request body you can specify a time period, number of directory levels, and the domains and directories to process. Please note that this API differs from our other report APIs in that the request body must be in JSON format. However, you can choose to obtain the response in either JSON or XML format.
Header |
Description |
Required |
Authorization |
Authorization string for the request |
Yes |
Host |
URI for the QUANTIL SDK (i.e., api.quantil.com) |
Yes |
Date |
The date and time of the request. |
Yes |
Accept |
Indicates the accepted format (i.e., application/xml or application/json) |
No |
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Request parameters",
"description": "Describes the input format for the /api/report/dirflow API",
"type":"object",
"properties": {
"dateFrom":{
"description": "RFC3339 formatted date indicating the starting date. Example: 2018-01-01T22:30:00+08:00. The timezone of the response data will be based on the timezone of the value of dateFrom.",
"type": "string"
},
"dateTo":{
"description": "RFC3339 formatted date indicating the ending date. Example: 2018-01-01T22:30:00+08:00",
"type": "string"
},
"dirHierarchy": {
"description": "Indicate the number of directory levels to process. It is a string whose value is 1, 2, 3, or 4.",
"type": "string"
},
"domainDir": {
"description": "This is an array of objects describing the domains and directories whose traffic should be summarized.",
"type": "array",
"items": { "$ref": "#/definitions/domaindefinition" }
}
},
"definitions": {
"domaindefinition" : {
"type": "object",
"maxItems": 20,
"properties": {
"domain": {
"description": "A domain whose traffic should be returned.",
"type": "string"
},
"dir": {
"description": "An optional field indicating the directories which should be processed. If unspecified, each directory under the domain will be summarized in the response. ",
"type": "array",
"items": {
"description": "a directory under the domain. It should begin and end with the '/' character, for example, '/mydirectory/'.",
"type": "string"
}
}
},
"required": ["domain"]
}
},
"required": ["dateFrom", "dateTo", "dirHierarchy", "domainDir"]
}
Note: If you do not explicitly specify the directories to summarize, we will try to return traffic for each directory under your domain considering the number of directory levels requested in dirHierarchy. If your domain contains more than 200 directories, you will get a DirExcessive response. The solution for this is to make separate API calls to fetch traffic for subsets of the directories within your domain. For example, if your domain has 450 directories, you could make three API calls to process 150 directories at a time.
POST /api/report/dirflow HTTP/1.1
Authorization: <authorization string>
Host: api.quantil.com
Date: <date>
Accept: application/xml
Here is the structure of a request using the curl utility.
curl -i --url https://api.quantil.com/api/report/dirflow/
-X POST
-u {user}: {password}
-H 'Date: Fri, 26 Oct 2012 06:33:26 GMT'
-H 'Accept: application/xml'
-H 'Content-Type: application/json'
-d '
{
<JSON REQUEST BODY GOES HERE>
}
'
curl -i --url 'https://api.quantil.com/api/dirflow' -X POST -u test:amn9BXnyZtq7jyVQZjBls0OBZk4= -H 'Date: Thu, 07 Aug 2018 14:31:12 PDT' -H 'Accept: application/xml' -d '
{
"dateFrom":"2018-01-01T22:30:00+08:00",
"dateTo":"2018-01-02T22:30:00+08:00",
"dirHierarchy":"1",
"domainDir":[
{
"domain":"test.com",
"dir":[
"/dir01/",
"/dir02/"
]
},
{
"domain":"b.com",
"dir":[
"/dir03/",
"/dir02/",
"/dir01/"
]
}
]
}'
HTTP/1.1 200 OK
Date: <date>
Content-Type: application/json; charset = utf-8
x-cnc-request-id: {id string auto generated by the QUANTIL server}
The following schema describes responses in JSON format.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Response",
"description": "Describes the JSON response for the /api/report/dirflow API",
"type":"object",
"properties": {
"result": {
"description": "This is an array of objects describing the traffic to directories of domains.",
"type": "array",
"items": { "$ref": "#/definitions/domainresponse" }
}
},
"definitions": {
"domainresponse" : {
"type": "object",
"properties": {
"domain": {
"description": "The domain whose traffic is returned.",
"type": "string"
},
"details": {
"description": "Contains the traffic organized by directory.",
"type": "array",
"items": { "$ref": "#/definitions/directoryresponse" }
}
},
"required": ["domain"]
},
"directoryresponse": {
"type": "object",
"properties": {
"dir": {
"description": "A directory under the domain.",
"type": "string"
},
"totalFlow": {
"description": "Traffic volume in megabytes",
"type": "string"
},
"bandwidthPeakValue": {
"description": "Peak bandwidth in Mbps",
"type": "string"
}
},
"required":["dir","totalFlow", "bandwidthPeakValue"]
}
},
"required": ["result"]
}
Note: The response will only include directories with traffic.
{
"result":[
{
"domain": "test.com",
"details":[
{
"dir":"/dir01/",
"totalFlow":"1000065.00001",
"bandwidthPeakValue":"2666.96124"
},
{
"dir":"/dir02/",
"totalFlow":"2000130.00002",
"bandwidthPeakValue":"39666.56120"
}
]
}
]
}
HTTP/1.1 200 OK
Date: <date>
Content-Type: application/xml; charset = utf-8
x-cnc-request-id: {id string auto generated by the QUANTIL server}
The following summarizes the XML syntax if you choose an XML response.
Element |
Description |
report |
Container for results. It consists of one <result> child element. |
result |
A container within the <report> element. This can contain zero or more <report> elements describing the traffic and bandwidth for individual directories. |
report |
A container within the <result> element. This describe traffic and bandwidth for a domain. It consists of two child elements <domain> and <details>. |
domain |
This is the domain for which statistics are provided. |
details |
This container has zero or more <detail> elements each describing the traffic for a directory. |
detail |
A container which describes the traffic for a directory. It consists of three child elements <dir>, <total-flow>, and <bandwidth-peak-value>. |
dir |
A directory within the domain |
total-flow |
Total traffic to the directory in megabytes. (i.e., 123.56789) |
bandwidth-peak-value |
Peak bandwidth in Mbps with granularity of five minutes. (i.e., 34.90124) |
HTTP/1.1 200 OK
Date: Fri, 08 Aug 2018 00:52:00 GMT
Accept-Ranges: bytes
Server: Reslet-Framework/2.1.0
Content-Type: application/xml;charset=UTF-8
Content-Length: 650
<?xml version="1.0" encoding="utf-8"?>
<report>
<result>
<report>
<domain>test.com</domain>
<details>
<detail>
<dir>/dir01/</dir>
<total-flow>1000065.00001</total-flow>
<bandwidth-peak-value>2666.96124</bandwidth-peak-value>
</detail>
<detail>
<dir>/dir02/</dir>
<total-flow>2000130.00002</total-flow>
<bandwidth-peak-value>39666.56120</bandwidth-peak-value>
</detail>
</details>
</report>
</result>
</report>
Error |
Description |
HTTP status code |
DirExcessive |
The number of directories exceeds the limit which defaults to 200. Note: This error is returned if you specify more directories than the limit in your request. The error is also returned but with status code 500 if your domain simply contains too many directories. In this case, you can make multiple API calls to process different subsets of directories at a time. |
400 |
DomainsExcessive |
The number of domains exceeds the limit. |
400 |
InvalidBody |
The request was incorrectly formatted. Please check the request body follows the specification. |
400 |
InvalidDatePeriod |
The date specified is invalid. |
400 |
InvalidDir |
The directory must start and end with '/'. |
400 |
InvalidDirHierarchy |
The directory level is invalid. |
400 |
NoSuchDomain |
The specified domain does not exist. |
404 |