Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new DNS analytics endpoint to OpenAPI spec #558

Merged
merged 12 commits into from
Feb 9, 2024
Merged

Add new DNS analytics endpoint to OpenAPI spec #558

Changes from 7 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0fddbfc
Change: Basic outline plus parameters
jacegu Jan 31, 2024
b9b11db
Change: Extract PaginationPage and PaginationPerPage
jacegu Jan 31, 2024
d8a967b
Change: Consolidate wording to match the one in the developer docs
jacegu Feb 1, 2024
77e9993
Change: Add response
jacegu Feb 1, 2024
9e438cd
Change: Remove duplicated line
jacegu Feb 1, 2024
92bc697
Change: Fix parameter definition
jacegu Feb 1, 2024
1308189
Change: Fix types in rows
jacegu Feb 1, 2024
30086e3
Update content/v2/openapi.yml
jacegu Feb 1, 2024
cfab17a
Update content/v2/openapi.yml
jacegu Feb 1, 2024
1de58d1
Change: Ditch enum and add example
jacegu Feb 1, 2024
5b02b7b
fixes typo, adds commas
itsalyse Feb 8, 2024
10e65f1
fixes typo
itsalyse Feb 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 165 additions & 30 deletions content/v2/openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@ info:
externalDocs:
url: 'https://developer.dnsimple.com'
security:
- basicAuth: []
- bearerAuth: []
- basicAuth: [ ]
- bearerAuth: [ ]
servers:
- url: 'https://api.dnsimple.com/v2'
description: DNSimple Production API
variables: {}
variables: { }
- url: 'https://api.sandbox.dnsimple.com/v2'
description: 'DNSimple Sandbox API used for testing'
tags:
Expand Down Expand Up @@ -48,7 +48,7 @@ paths:
/accounts:
get:
description: Lists the accounts the current authenticated entity has access to.
parameters: []
parameters: [ ]
operationId: listAccounts
tags:
- accounts
Expand All @@ -68,7 +68,7 @@ paths:
/whoami:
get:
description: Retrieves the details about the current authenticated entity used to access the API.
parameters: []
parameters: [ ]
operationId: whoami
tags:
- identity
Expand Down Expand Up @@ -273,24 +273,6 @@ paths:
'404':
$ref: '#/components/responses/404'
summary: Add a collaborator
'/{account}/domains/{domain}/collaborators/{collaborator}':
delete:
description: Removes a collaborator from the domain.
parameters:
- $ref: '#/components/parameters/Account'
- $ref: '#/components/parameters/Domain'
- $ref: '#/components/parameters/Collaborator'
operationId: removeDomainCollaborator
tags:
- domain collaborators
responses:
'204':
description: Successfully removed collaborator
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
summary: Remove a collaborator
'/{account}/domains/{domain}/dnssec':
get:
description: Gets the DNSSEC status for an existing domain.
Expand Down Expand Up @@ -758,8 +740,8 @@ paths:
type: array
items:
type: string
default: []
example: ['docs.example.com', 'status.example.com']
default: [ ]
example: [ 'docs.example.com', 'status.example.com' ]
signature_algorithm:
description: 'Optional string to determine the signature algorithm to be used. Either `ECDSA` or `RSA`'
type: string
Expand Down Expand Up @@ -1601,7 +1583,6 @@ paths:
'404':
$ref: '#/components/responses/404'
summary: Delete a primary server

'/{account}/secondary_dns/primaries/{primaryserver}/link':
put:
description: Link the primary server to a secondary zone.
Expand Down Expand Up @@ -1651,6 +1632,7 @@ paths:
'404':
$ref: '#/components/responses/404'
summary: Unlink a primary server from a secondary zone

'/{account}/secondary_dns/zones':
post:
summary: Create a secondary zone
Expand Down Expand Up @@ -2168,6 +2150,24 @@ paths:
'400':
$ref: '#/components/responses/400'
summary: Start registrant chnange
'/{account}/domains/{domain}/collaborators/{collaborator}':
delete:
description: Removes a collaborator from the domain.
parameters:
- $ref: '#/components/parameters/Account'
- $ref: '#/components/parameters/Domain'
- $ref: '#/components/parameters/Collaborator'
operationId: removeDomainCollaborator
tags:
- domain collaborators
responses:
'204':
description: Successfully removed collaborator
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
summary: Remove a collaborator
'/{account}/registrar/registrant_changes/check':
post:
description: Retrieves the requirements of a registrant change.
Expand Down Expand Up @@ -2697,6 +2697,107 @@ paths:
'204':
description: Successfully deleted a webhook.
summary: Delete a webhook
'/{account}/dns_analytics':
get:
description:
Queries and returns DNS Analytics data available for the provided query parameters.
This API is currently in Public Beta. During the Public Beta period changes may occur at any time.
parameters:
- $ref: '#/components/parameters/Account'
- name: start_date
description:
Only include results after the given date. Format is ISO8601 (YYYY-MM-DD).
It can be at most 31 days away from the end_date.
If omitted it defaults to 31 days ago.
style: form
in: query
required: false
schema:
$ref: '#/components/schemas/Date'
- name: end_date
description:
Only include results before the given date. Format is ISO8601 (YYYY-MM-DD).
It can be at most 31 days away from the start_date.
If omitted it defaults to 1 day ago.
style: form
in: query
required: false
schema:
$ref: '#/components/schemas/Date'
- name: groupings
description:
How to group the results about the account's DNS analytics.
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.
style: form
in: query
required: false
schema:
type: string
enum:
- 'date'
- 'volume'
- 'zone_name'
- $ref: '#/components/parameters/SortDNSAnalytics'
- $ref: '#/components/parameters/PaginationPage'
- $ref: '#/components/parameters/PaginationPerPage'
responses:
'200':
description: Successfully retrieved DNS analytics data.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
rows:
type: array
items:
anyOf:
- type: integer
- type: string
- $ref: '#/components/schemas/Date'
example: [example.com,102985]
jacegu marked this conversation as resolved.
Show resolved Hide resolved
headers:
type: array
items:
type: string
example: zone_name,volume
jacegu marked this conversation as resolved.
Show resolved Hide resolved
query:
type: object
properties:
account_id:
type: integer
start_date:
$ref: '#/components/schemas/Date'
end_date:
$ref: '#/components/schemas/Date'
sort:
type: string
description: Sorting applied to the returned data.
example: "date:asc,zone_name:asc"
groupings:
type: string
description: Grouping applied to the returned data.
example: "date,zone_name"
page:
type: integer
description: The returned page numeber.
example: 1
per_page:
type: integer
description: The page size used to generate the data.
example: 1000
pagination:
$ref: '#/components/schemas/Pagination'
operationId: dnsAnalytics
tags:
- billing
- zones
summary: Analytics about DNS queries
components:
securitySchemes:
basicAuth:
Expand Down Expand Up @@ -2922,6 +3023,25 @@ components:
description: Only include results with a contact_id field exactly matching the given string
schema:
type: string
PaginationPage:
description: The page of the results requested. Defaults to 1.
name: page
style: form
in: query
required: false
schema:
type: integer
PaginationPerPage:
description:
The amount of rows to return in each page.
The default is usually 100.
There are endpoints that override this default to accommodate specific use cases.
name: per_page
style: form
in: query
required: false
schema:
type: integer
SortCertificates:
description: Sort results. Default sorting is by id.
name: sort
Expand Down Expand Up @@ -2963,6 +3083,21 @@ components:
- 'label:desc'
- 'email:asc'
- 'email:desc'
SortDNSAnalytics:
description: Sort results. Default sorting policy is by ascending date, then ascending zone_name.
name: sort
style: form
in: query
required: false
schema:
type: string
enum:
- 'date:asc'
- 'date:desc'
- 'volume:asc'
- 'volume:desc'
- 'zone_name:asc'
- 'zone_name:desc'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multiple sorting criteria can be defined. In fact, the default is "date:asc,zone_name:asc". Can we just not provide the enum here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just followed the example of other endpoints in which we are providing the enum, even when the values can be combined. Not sure if I did the right thing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how to interpret enum either...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that we're not using them correctly if values can be combined https://swagger.io/docs/specification/data-models/enums/

It sounds like we would need to list all permutations under all possible sorting, which feels wrong to do. Maybe we should not have enum unless there's a finite list of values our customers need to pick from.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was looking at the same thing and I agree: I do not think this is the correct use. Will update this momentarily.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See: 1de58d1

SortDomains:
description: Sort results. Default sorting is ascending by name.
name: sort
Expand Down Expand Up @@ -4594,7 +4729,7 @@ components:
name: 'Primary Server'
ip: '1.1.1.1'
port: 4567
linked_secondary_zones: ['example.com']
linked_secondary_zones: [ 'example.com' ]
created_at: '2016-08-11T10:16:03Z'
updated_at: '2016-08-11T10:16:03Z'
Push:
Expand Down Expand Up @@ -4657,7 +4792,7 @@ components:
contact_id: 2
domain_id: 2
state: completed
extended_attributes: { "x-fi-registrant-idnumber":"1234" }
extended_attributes: { "x-fi-registrant-idnumber": "1234" }
registry_owner_change: false
irt_lock_lifted_by: '2013-12-08'
created_at: '2013-11-08T17:23:15Z'
Expand All @@ -4678,7 +4813,7 @@ components:
example:
contact_id: 2
domain_id: 2
extended_attributes: [{ "name":"x-fi-registrant-birth-date" ,"title":"The registrant's birth date", "description":"Format is: YYYY-MM-DD.","required":false,"options":[] }]
extended_attributes: [ { "name": "x-fi-registrant-birth-date" ,"title": "The registrant's birth date", "description": "Format is: YYYY-MM-DD.","required": false,"options": [ ] } ]
registry_owner_change: false
SecondaryDNS:
type: object
Expand Down Expand Up @@ -5823,7 +5958,7 @@ components:
example:
domain_id: "example.com"
contact_id: "2"
extended_attributes: { "x-fi-registrant-idnumber":"1234" }
extended_attributes: { "x-fi-registrant-idnumber": "1234" }
RegistrantChangeCheck:
description: Contact change attributes
required: true
Expand Down
Loading