June 6, 2016

UltraDNS REPORTING SERVICE Quick Start

Instructions and Examples for using the UltraDNS Reporting Service API

Neustar UltraDNS Reporting Service Quick Start User Guide

June 6, 2016

This document is for informational purposes only. NEUSTAR MAKES NO WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Neustar.

Neustar may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Neustar, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.

© 2016 Neustar, Inc. All rights reserved.

Neustar Ultra Services and UltraCare are Neustar’s trademarks and any use of these or any other Neustar mark without Neustar’s express written consent is prohibited. All other trademarks and/or service marks identified or referenced are the property of their respective owners and subject to their usage requirements.

Table of Contents

Page 3 of 19

Table of Contents Table of Contents .......................................................................................................... 3

About This Document ................................................................................................ 5 Document Revisions ................................................................................................. 5

Reporting Service ......................................................................................................... 6

Overview ................................................................................................................... 6 Authentication ........................................................................................................... 6 Authorization ............................................................................................................. 6

Authentication ............................................................................................................... 7

Authentication DTO ............................................................................................................. 7

Report DTOs ............................................................................................................. 9

Getting and Using Postman ....................................................................................... 10

Getting Postman ..................................................................................................... 10 Using Postman ........................................................................................................ 10

Support ........................................................................................................................ 19

Table of Contents

Page 4 of 19

List of Figures and Tables Table 1 Authentication DTOs .......................................................................................... 7 Figure 1 Import from Link .............................................................................................. 10 Figure 2 Update Username and Password .................................................................... 12 Figure 3 Response to “get_token” request .................................................................... 13 Figure 4 Post GET TaskID ............................................................................................ 14 Figure 5 Projected Query Volume Report in JSON format............................................. 15 Figure 6 Viewing the Projected Query Volume Report in CSV format ........................... 16 Figure 7 Getting the Projected Query Volume Report in CSV format ............................ 17 Figure 8 Getting Source Code ....................................................................................... 18

List of Examples JSON Example: Authorization Request ........................................................................... 7 JSON Example: Authentication Return ........................................................................... 7

About This Document

Page 5 of 19

About This Document The purpose of this document is to provide information on how to quickly get started, in minutes, using the UltraDNS REST API Reporting interface via the publicly available Postman API, and the Postman reporting collection provided by Neustar. This document will provide information on how to access the Postman API collection, provide the necessary authentication information, submit an API call, get output back and generate source code that can be ported into other applications.

Document Revisions The following table provides a list of major revisions made to this document since its initial release. Be sure you are using the current version of the document.

As always, if you have comments or suggestions for this guide, contact Neustar at: www.support.neustar.

Date Changes 2016-04-28 First release of the Quick Start User Guide 2016-05-26 Updated Postman information and added new reports - Zone Query Volume and Zone

Daily Query Volume report information.

Reporting Service Overview

Page 6 of 19

Reporting Service

Overview Reporting Service is a Restful web service that provides Ultradns customers access to UltraDNS reports via an API interface. This service supports user authentication via Tokens and authorization via report level configurations in reporting service /user account settings, similar to those already in place in the REST API. The reporting data retrieved is returned to the customer in response to Reporting service API calls.

Authentication Authentication via the Reporting Service is the initial step in which the customer’s first step is to acquire an authentication token to use, which will also be usable for future reporting service calls. The Reporting Service Authentication works in the same way that is outlined in the Response to API Calls section of this guide.

Authorization The Authorization process is outlined by the following scenarios, and is based upon the type of report that is being requested.

A. If the report requested by the user is a Standard report, the user does not need to have advanced reporting authorization set at the user account level.

B. If the report requested by the user is an Advanced report, then the user’s account will be checked for the Advanced reporting authorization before continuing.

C. If the report requested by the user is for an account that the user belongs to, the user will be granted access to the report.

D. If the report requested by the user is for an account that the user has access to, the user will be granted access to the report.

• Once a user has been authorized for a specified report, no additional authorizations will be required when retrieving information for the report, until a new report is requested.

Advanced reporting allows you to analyze time data to the minute, and location data to the client Class C address level. By comparison, the standard reporting package restricts analysis to only the hour and country level.

Authentication

Page 7 of 19

Authentication Method and URI:

POST https://reports.ultradns.com/v1/authentication/token

Parameters: Authentication DTO

Body: None

Responses: Status Code 200 with “OK” message returned, with:

Errors: An error code is returned under the following conditions:

• Error Code 401 – “Invalid username and password combination.”

• Error Code 400 – “grant_type not supported.”

JSON Example: Authorization Request POST https://reports.ultradns.com/v1/authentication/token HTTP/1.1 Host: localhost:8080 Content-Type: application/x-www-form-urlencoded grant_type=password&username=teamrest&password=*******

JSON Example: Authentication Return Status 200 OK { "token_type": "Bearer", "refresh_token": "cd211859703e484fad41c0abccbaa298961f371e5f", "access_token": "0344529d99ec4eb79ea17a744f", "expires_in": "3600", }

Authentication DTO

Table 1 Authentication DTOs

Field Description Type

ResponseBody Description

token_type The Type of Token (usually “Bearer”) in reporting service.

refresh_token The Token used to generate a new set of tokens.

access_token The Token used to access other services before expiration.

expires_in The time in seconds the Token will expire.

Authentication

Page 8 of 19

grant_type The grant type must be the “password” if used with username and password.

The grant type must be “refresh_token” if used with a refresh token.

String. Required.

username The username of the user that is logging in.

String. Required.

password The password for the user logging in.

String. Required.

refresh_token The Token used to generate a new set of tokens.

String.

Authentication

Page 9 of 19

Report DTOs Report DTOs are specific to each report type. Information for each available API report is documented in the UltraDNS REST API User Guide. The User Guide is available off of the UltraDNS management portal GUI under “Support”.

The URL used to access the REST API reporting service is different than the URL for the other UltraDNS API calls. The URL for ALL reporting service calls is https://reports.ultradns.com/v1/ (followed by specific API call).

Getting and Using Postman

Page 10 of 19

Getting and Using Postman

Getting Postman Open the Google Chrome Browser and get the Postman application from the following location: https://www.getpostman.com/ Or, if you are familiar with the Chrome Web Store, you can search for Postman from the search bar.

You do not need to create an account to login unless you choose to. You can complete all the necessary steps as an anonymous user.

Using Postman 1. Get the Neustar REST API Reporting collection

a. Click on Collections from the left hand navigation pane, and then select Import at the top of the screen.

b. Select Import From Link. c. Enter the URL for the Neustar collection:

https://www.getpostman.com/collections/27d37d3ec53b5b499804

Figure 1 Import from Link

Getting and Using Postman

Page 11 of 19

Files and their usage in the Neustar UltraDNS REST API Reporting Postman Collection.

File Name in Postman Collection

Contents

reporter get token Security - A POST request for an authorization token. common first step for all reporting API calls

Input: Security credentials;

Output: Security token that will be used in all subsequent calls.

get <report name> Taskid Report Submission - A GET request for a report that returns a task id.

Input: Report DTO (contains report name) and security token.

Output: A report task id

get <report name> Report Output - A GET request with the report task id and security token that returns the report output.

Input: Task Id and security token

Output: Report output or report generation status.

Report Name Report Name Abbreviation in Postman Collection

Project Query Volume PQV

Zone Query Volume ZQV

Zone Daily Query Volume ZDQV

Getting and Using Postman

Page 12 of 19

2. Update the Username and Password fields, and then get the API Security Token. a. Highlight the POST Reporter Get Token call from the folder. b. Replace <user_name> and <user_password> with your UltraDNS login

credentials. c. Click Save in the upper right hand corner to retain the authentication / login

information for future use. d. Click Send. e. You will get a security/access token from the body of the response.

Figure 2 Update Username and Password

Getting and Using Postman

Page 13 of 19

3. The output of the reporter get token request is the security token (Figure 3). The Postman script will automatically save and passes the access_token to the subsequent API requests.

Figure 3 Response to “get_token” request

Congratulations! You just completed your first REST API Reporting request and response.

Getting and Using Postman

Page 14 of 19

4. Send the report request a. Click on the POST get TaskId. b. Click Send.

Figure 4 Post GET TaskID

This sends the report request along with the authentication token to the URL: https://reports.ultradns.com/v1/reports/dns_resolution/projected_query_volume

The response to this request is the report request task id (requestId). The report task id is subsequently used to request the return of the report output. The Postman script will automatically pass this task id to the next step.

5. Getting the Project Query Volume (PQV) report. a. Get the Project Query Volume (PQV) report in JSON format

i. Click GET PQV report ii. Click Send.

The output will appear on the Postman screen in the Postman “Pretty” format).

Getting and Using Postman

Page 15 of 19

Figure 5 Projected Query Volume Report in JSON format

This sends the get report output request along with the authentication token to the URL: https://reports.ultradns.com/v1/requests/{{taskId}}

b. Viewing the report in the Postman GUI in a .csv format i. Click on Body below the URL line, and then select the option Raw. ii. The output will now appear on the Postman screen in the Postman “.csv”

format).

Getting and Using Postman

Page 16 of 19

Figure 6 Viewing the Projected Query Volume Report in CSV format

c. Getting the Project Query Volume (PQV) report generated in .csv format i. Select the GET PQV report from the left hand side of the screen. ii. Click the Headers option. iii. On the Accept line, change the value from application/json to text/csv. iv. Click Send.

Getting and Using Postman

Page 17 of 19

Figure 7 Getting the Projected Query Volume Report in CSV format

6. Getting the source code for your own application. a. Select the code you want. b. Click on Generate Code in the upper right hand side of the screen. c. Copy (ctrl+c) to your own application.

Getting and Using Postman

Page 18 of 19

Figure 8 Getting Source Code

Getting and Using Postman

Page 19 of 19

Support The Postman collection of API calls was tested and verified as working by Neustar at the time of publication. Differences between the Neustar environment and your environment may impact the successful usage of the API calls provided. You’re encouraged to thoroughly test the Postman collection provided. The collection of API calls is maintained by Neustar on a best effort basis.

If you encounter issues with generically using Postman, please consult the public domain information on Postman. For specific issues encountered with the REST API Reporting interface inputs or outputs, please reference the full REST API reporting documentation which is included in the UltraDNS REST API document. If you still need assistance, contact Neustar Technical Support.

Neustar Support 1 (844) NSR-CUST, 1 (844) 677-2878, +1 571-434-6700, www.support.neustar