neustar ultradns reporting service quick start user guide ... · reporting service is a restful web...
TRANSCRIPT
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