diff --git a/content/v2.markdown b/content/v2.markdown index d4292be0..7aee8d80 100644 --- a/content/v2.markdown +++ b/content/v2.markdown @@ -348,6 +348,9 @@ For example: https://api.dnsimple.com/v2/1010/domains?per_page=100&page=2 + +Some endpoints can define specific defaults and maximum values for the `per_page` argument. + ## Filtering diff --git a/content/v2/dns-analytics.markdown b/content/v2/dns-analytics.markdown new file mode 100644 index 00000000..f2c882b9 --- /dev/null +++ b/content/v2/dns-analytics.markdown @@ -0,0 +1,114 @@ +--- +title: DNS Analytics API | DNSimple API v2 +excerpt: This page documents the DNS Analytics API v2 endpoint. +--- + +# DNS Analytics + +* TOC +{:toc} + + + This API is currently in Public Beta. During the Public Beta period, changes may occur at any time. + + +## Query DNS Analytics data {#query} + +Queries and returns DNS Analytics data available for the provided query parameters: + +~~~ +GET /:account/dns_analytics +~~~ + +### Parameters + +Name | Type | Description +-----|------|------------ +`:account` | `integer` | The account ID + +### Groupings + +Name | Description +-----|------------ +`:zone_name` | Group rows by zone name +`:date` | Group rows by date + +No groupings will be applied by default unless specified. +Multiple groupings can be provided, separated by a comma. + + +Applying groupings to the query will add columns to the response payload. + + +### Filters + +Name | Default value | Description +-----|---------------------------------|------------ +`:start_date` | 31 days before the current date | Only include results starting from the provided date +`:end_date` | The day before the current date | Only include results up to the provided date + + +Both dates are **inclusive**, and must be provided in **ISO 8601 format** (e.g. `2024-08-01`). + + + +The maximum allowed date range is 31 days. + + +### Sorting + +For general information about sorting, please refer to the [main guide](/v2/#sorting). + +Name | Description +-----|------------ +`zone_name` | Sort rows by zone name +`date` | Sort rows by date +`volume` | Sort rows by query volume + +The default sorting policy is by ascending `date`, then ascending `zone_name`. + +### Pagination + +Pagination is supported in this endpoint: + +- The default page size (`per_page` query parameter) is 1,000. +- The maximum supported page size (`per_page` query parameter) is 10,000. +- Please refer to the [main guide](/v2/#pagination). + +### Example: get total query volume data for the entire account + +~~~ +curl -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' \ + https://api.dnsimple.com/v2/dns_analytics +~~~ + +### Example: get the top ten zones by volume in December, 2023 + +~~~ +curl -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' \ + https://api.dnsimple.com/v2/dns_analytics?groupings=zone_name&sort=volume:desc&per_page=10&start_date=2023-12-01&end_date=2023-12-31 +~~~ + +### Example: get daily query volume for all zones in the account for the last 31 days, with custom sorting + +~~~ +curl -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' \ + https://api.dnsimple.com/v2/dns_analytics?groupings=date,zone_name&sort=date:desc,zone_name:asc +~~~ + +### Response + +Responds with HTTP 200. + +##### Example + +~~~json +<%= pretty_print_fixture("/api/dnsAnalytics/success.http") %> +~~~ + +### Errors + +Responds with [HTTP 401](/v2#unauthorized) if there are authentication issues. diff --git a/fixtures/v2/api/dnsAnalytics/success.http b/fixtures/v2/api/dnsAnalytics/success.http new file mode 100644 index 00000000..d142db6b --- /dev/null +++ b/fixtures/v2/api/dnsAnalytics/success.http @@ -0,0 +1,20 @@ +HTTP/1.1 200 OK +Server: nginx +Date: Tue, 14 Jun 2016 12:02:58 GMT +Content-Type: application/json; charset=utf-8 +Connection: keep-alive +X-RateLimit-Limit: 2400 +X-RateLimit-Remaining: 2391 +X-RateLimit-Reset: 1465908577 +ETag: W/"9ef3b4bf1f441a9b1cd6d7041bc181aa" +Cache-Control: max-age=0, private, must-revalidate +X-Request-Id: f705b65b-3589-43ad-97ca-3b2821d49d81 +X-Runtime: 0.012661 +X-Content-Type-Options: nosniff +X-Download-Options: noopen +X-Frame-Options: DENY +X-Permitted-Cross-Domain-Policies: none +X-XSS-Protection: 1; mode=block +Strict-Transport-Security: max-age=31536000 + +{"data": {"headers": ["zone_name", "date", "volume"], "rows": [["bar.com", "2023-12-08", 1200], ["bar.com", "2023-12-09", 1200], ["bar.com", "2024-01-07", 1200], ["bar.com", "2024-01-08", 1200], ["example.com", "2023-12-08", 1200], ["example.com", "2023-12-09", 1200], ["example.com", "2024-01-07", 1200], ["example.com", "2024-01-08", 1200], ["foo.com", "2023-12-08", 1200], ["foo.com", "2023-12-09", 1200], ["foo.com", "2024-01-07", 1200], ["foo.com", "2024-01-08", 1200]]}, "query": {"account_id": 1, "start_date": "2023-12-08", "end_date": "2024-01-08", "sort": "zone_name:asc,date:asc", "page": 0, "per_page": 100, "groupings": "zone_name,date"}, "pagination": {"current_page": 0, "per_page": 100, "total_entries": 93, "total_pages": 1}} diff --git a/layouts/sidebar.html b/layouts/sidebar.html index 4a74cc30..1583d8be 100644 --- a/layouts/sidebar.html +++ b/layouts/sidebar.html @@ -50,6 +50,7 @@
  • +
  • DNS Analytics