Click or drag to resize

DegreeDaysApi Class

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

Namespace: DegreeDays.Api
Assembly: DegreeDays (in DegreeDays.dll) Version: 1.4
Syntax
public sealed class DegreeDaysApi

The DegreeDaysApi type exposes the following members.

Constructors
 NameDescription
Public methodDegreeDaysApi(IRequestProcessor) Constructs a DegreeDaysApi object that internally uses the specified IRequestProcessor.
Public methodDegreeDaysApi(AccountKey, SecurityKey) Constructs a DegreeDaysApi object that internally uses a default IRequestProcessor configured with the specified access keys.
Top
Properties
 NameDescription
Public propertyDataApi Gets a non-null DataApi object, providing easy, type-safe access to the API's data-related operations.
Public propertyRegressionApi Gets a non-null RegressionApi object, providing easy, type-safe access to the API's regression-related operations.
Top
Remarks

To create a DegreeDaysApi object, you'll typically want to use this constructor. For example:

DegreeDaysApi api = new DegreeDaysApi(
    new AccountKey("test-test-test"),
    new SecurityKey("test-test-test-test-test-test-test-test-test-test-test-test-test"));

The API access keys above (account key and security key) are for the free test account, which is heavily limited but usable for basic development and testing. For much more flexibility and production use, you can sign up for a full Degree Days.net API account to get your own API access keys.

Assuming you have a DegreeDaysApi object called api, as in the example code above, then you can make three main types of request (and get three main types of response) using the objects and methods accessible through that api object. The links below have more information and sample code for each:

More on 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 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.

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 GetLocationData(LocationDataRequest) to see the exceptions that can be thrown if the API servers can't process a LocationDataRequest. The exceptions should help you 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 on signup. 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, please see the notes in AccountKey and SecurityKey.

To get your own API access keys, you can sign up for an API account here. Or, for basic development and testing, you can try out the free test account.

Using a DegreeDaysApi object

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.

For more information and code samples on how to use a DegreeDaysApi object that you have created (let's call it api as per the example further above), please see the docs for the 3 main methods accessible through it:

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