net.degreedays.api

Class DegreeDaysApi

java.lang.Object

net.degreedays.api.DegreeDaysApi

public final class DegreeDaysApi
extends java.lang.Object

The starting point for all API operations. If you're new to this API, read the docs for this class first.

How the API works: requests, responses, and errors

• You create a Request object that specifies what you want the API to do. There are different types of Request for different API operations, like LocationDataRequest for requesting a set of degree-day data.
• Your Request gets processed. (Internally this library will turn your request into XML, send it to the API servers, and parse the XML response that the servers send back.)
• You'll get a Response object back (assuming no errors). There are different types of Response, mirroring the different types of Request. For example, if you use a LocationDataRequest to request some degree-day data, successful processing will give you a LocationDataResponse in return.

If something goes wrong in sending your request to the API servers, or in getting your response back, you'll get a TransportException. Typically that means there was a network error of some sort.

If your request was transported to the API servers OK, but couldn't be processed properly, you'll get a RequestFailureException instead of a Response. There are different types of RequestFailureException for the different types of Request. For example, take a look at the docs for DataApi.getLocationData(LocationDataRequest) to see the exceptions that can be thrown if the API servers can't process a LocationDataRequest. The exceptions should help you to determine the cause of the failure and decide what to do next.

API access keys: the account key and the security key

Every customer's API account is associated with two access keys: a public "account key" and a private "security key", both of which are generated automatically when the account is created. These keys are used to secure each request sent to the API by the customer (or by software trusted to work on their behalf), to protect the API usage that the customer has paid to enable.

The account key is used to uniquely identify the customer account. It is a public key in the sense that there is no need to keep it secret.

Here's an example account key:

k9vs-e6a3-zh8r

The security key is a private key that should be kept secret. In this respect it is like a password. The only entities that should have access to the security key are: Degree Days.net (systems and staff), the API account holder(s), and any trusted software systems that the API account holder(s) are using to manage their interactions with the API.

Here's an example security key:

b79h-tmgg-dwv5-cgxq-j5k9-n34w-mvxv-b5be-kqp5-b6hb-3bey-h5gg-swwd

For more on the format of these access keys, see the notes in AccountKey and SecurityKey.

Creating a DegreeDaysApi object

A DegreeDaysApi object needs a RequestProcessor to function. The RequestProcessor does the real work of turning requests into responses, and the DegreeDaysApi wraps that functionality up into a (hopefully) user-friendly interface.

You'll typically want to create a DegreeDaysApi object using this constructor. For example:

 DegreeDaysApi api = new DegreeDaysApi(
     new AccountKey("k9vs-e6a3-zh8r"),
     new SecurityKey("b79h-tmgg-dwv5-cgxq-j5k9-n34w-mvxv-b5be-kqp5-b6hb-3bey-h5gg-swwd"));
 

Internally, that constructor will create and store an XmlHttpRequestProcessor with your access keys and a default configuration. Your DegreeDaysApi object will use that internal XmlHttpRequestProcessor object to process all the requests you make through the dataApi() (and, later, an accountApi() that we intend to introduce at some point).

You might sometimes want to pass in a custom RequestProcessor using this constructor. Maybe a mock RequestProcessor for testing, or a RequestProcesor that you've customized for use in your application (e.g. one that uses HttpClient instead of java.net for its HTTP processing).

You'd typically create just one DegreeDaysApi object for use throughout your application. The default configuration is perfectly safe for use from multiple threads. But there's nothing to stop you creating and using as many instances as you like.

Using a DegreeDaysApi object

Here's an example of how you might fetch some degree-day data. We'll assume that you have already created the DegreeDaysApi object called api (see above), and created the LocationDataRequest object called request:

 LocationDataResponse response = api.dataApi().getLocationData(request);
 

Assuming no exception was thrown, the response object should contain the data you requested.

See the DataApi class documentation for a more complete example that includes creating the LocationDataRequest object and getting the degree-day values out of the LocationDataResponse object.

This class is designed to be safe for use from multiple concurrent threads. However, if you create a customized instance of this class (using a RequestProcessor that you have written or customized), then the thread-safety of its operation will depend on the thread-safety of that RequestProcessor.

Constructor Summary

Constructors

Constructor and Description
DegreeDaysApi(AccountKey accountKey, SecurityKey securityKey) Constructs a DegreeDaysApi object that internally uses a default RequestProcessor configured with the specified access keys.
DegreeDaysApi(RequestProcessor requestProcessor) Constructs a DegreeDaysApi object that internally uses the specified RequestProcessor.

Method Summary

Modifier and Type	Method and Description
DataApi	dataApi() Returns a non-null DataApi object, providing easy, type-safe access to the API's data-related operations.
RegressionApi	regressionApi() Returns a non-null RegressionApi object, providing easy, type-safe access to the API's regression-related operations.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DegreeDaysApi

public DegreeDaysApi(AccountKey accountKey,
                     SecurityKey securityKey)

Constructs a DegreeDaysApi object that internally uses a default RequestProcessor configured with the specified access keys.

Parameters:

accountKey - a non-null AccountKey object - a wrapper around the string account key that identifies the Degree Days.net API account.

securityKey - a non-null SecurityKey object, a wrapper around the string security key associated with the account.

Throws:

java.lang.NullPointerException - if accountKey or securityKey is null.

See Also:

API access keys

DegreeDaysApi

public DegreeDaysApi(RequestProcessor requestProcessor)

Constructs a DegreeDaysApi object that internally uses the specified RequestProcessor.

We can think of two main reasons that you might want to use this instead of the constructor that creates a default RequestProcessor automatically:

1. So that you can pass in your own mock RequestProcessor for testing.
2. So that you can pass in a customized version of XmlHttpRequestProcessor. You might, for example, want to change the endpoint URL, or swap the default java.net-based HttpRequestDispatcher for one that uses HttpClient instead (if your app uses HttpClient elsewhere).

Parameters:

requestProcessor - the non-null RequestProcessor object to use internally for all operations.

Throws:

java.lang.NullPointerException - if requestProcessor is null.

Method Detail

dataApi

public DataApi dataApi()

Returns a non-null DataApi object, providing easy, type-safe access to the API's data-related operations.

regressionApi

public RegressionApi regressionApi()

Returns a non-null RegressionApi object, providing easy, type-safe access to the API's regression-related operations.

Since:

1.4