A Walkthrough of the NetDNA API Console
August 20, 2012 | Robert Gibb
The NetDNA REST API allows you to create applications that interact with NetDNA’s system resources such as: Users, Zones, Accounts, and Reports. And the easiest way to develop your application is using the API Console. Using this facility enables you to easily view the JSON response of different API calls in real time without writing a single line of code. Viewing the responses in this manner allows you to conveniently see the actual responses, so it will be easier to write and debug your code.
Having this ability is very handy in building and debugging your applications. It is also important to note that all JSON responses of the API returns the proper HTTP status code for each request. The first parameter in the JSON response,
code, is the first one you should check before you process anything. This is the value of the HTTP status code response from your request and this will determine the kind of operation you will need to do in the application you are building. As a reference, the following are the HTTP status codes returned by the API:
|304||Not Modified||There is no new data to return.|
|400||Bad Request||The request is invalid.|
|401||Unauthorized||Authentication credentials are missing or incorrect|
|403||Forbidden||The request is understood, but is refused.|
|404||Not Found||The resource requested, such as a user, does not exist.|
|406||Not Acceptable||Returned when an invalid format is specified in the request.|
|420||Rate Limited||Returned by the API when you are rate limited.|
|500||Internal Server Error||Something is broke. Please contact an administrator|
|502||Bad Gateway||The API is down.|
|503||Service Unavailable||The API servers are up, but are unavailable.|
|504||Gateway Timeout||The API servers are up, but did not receive a timely response.|
The API Console can be accessed from the top level menu after you log in to your account or directly access it using this URL – https://developer.netdna.com/api/console.
The NetDNA API is grouped into four major categories: Accounts, Users, Zones, and Reports. And each category is further subdivided into different API groups based on the kind of operations they perform. For example, the Pull Zone API is actually classified under the Zones API, but it has its own group to make it easier to view all operations available for Pull Zones. The same sub-group applies for the Reports API.
The are four methods you can use in this category – Get Account Information, Update Account Information, Get Account Information, and Update Address Information. The methods you can use in this category are pretty straightforward:
With the Users API, you can manage your users in your account. Using the Users API is also very easy, and there are five operations available, namely — get a list of users in your account, create a new user, retrieve a specific user, update user based on
user_id, and delete a specific user.
The Zone API has many available methods you can use to query the zones in your account. It is quite extensive and it will allow you to query data from your Pull, Push, VOD, and Live zones.
The available methods in this category allows you to get statistics from your account which can be broken up by
report_type, which can be
monthly. Most of the methods available have a
date_to parameters, which give you the option to specify the start and end date of the statistics you want to query. You should also consider that all dates are in GMT timezone. This implies that you will need to use date conversions if you intend to present you data in your local time. Another important parameter you need to consider is the
nopaginate parameter which is set to
0by default. This parameter is crucial if you want the JSON response to return all the records available in one request. This, however, is not available in the API Console but very important to consider when you build your applications.
report_type parameter allows you to specify the level of detail of your API request which can be hourly, daily, or monthly. If you leave this parameter empty, the API will return the total summary based on the default values
date_from and date_to
These two parameters are the start date and end date of your API request and are in the following format: yyyy-mm-dd. By default, the
date_from parameter is set one month before the current GMT date. For example, if the current GMT date today is 2012-08-02, the
date_from parameter has value of 2012-07-02. These two parameters are usually optional by default, and if empty, the API will just return the summary data for the default start and end dates. You also need to consider that if you set the
report_type parameter to
date_to parameters will use hour value of the date you specify, hh:mm, to 00:00. This means that if you want to query the hourly statistics for a specific date, say 2012-08-01, your
end_date parameter should be 2012-08-02, to include all the hourly data until the last hour of 2012-08-01. You can verify this in the API Console by entering
hourly in the
report_typefield to any of the Reports API methods.
nopaginate parameter allows you to inform the NetDNA API that you want all the records to be available in one request. By default, the
nopaginate parameter is set to 0, and the API returns the records in sets of 50. This parameter,
nopaginate, is not available for use in the API Console, but you might need to consider using it when building your application. You just need to append this parameter at the end of your API request such as the following:
Using the API Console is your best companion to develop your applications that will interact with the NetDNA API. It gives you several options to query the data in your account, and see the actual JSON responses in real time. It also lets you save a lot of time in testing and verifying the behaviour of your applications.