Introduction

WeatherSentry Web Services from DTN provides your organization with the highly accurate weather observations and forecasts relied on worldwide to protect people, resources and profitability. These forecasts are top ranked by the independent agency ForecastWatch.com as the most accurate among industry providers.

These web services permit the retrieval of data using the REST standard.

XSD’s

The XSD’s for the REST web service can be found here: http://weather.dtn.com/rest-3.4/doc/

Terminology

Client

An HTTP client capable of making requests.

Credentials

A unique username and password pair.

Nonce

An arbitrary number used only once to sign a cryptographic communication.

OAuth

An open protocol standard that allows secured API authorization in a simple and standard method from desktop and web applications.

REST

Representational State Transfer

Server

DTN’s WeatherSentry (REST) Web Service
References

Requests

Authentication of requests is handled through usage of one of two security protocols: the OAuth standard, or the Basic standard. Basic authentication is the simplest technique for enforcing access controls to web resources because it doesn’t require cookies, session identifier and login pages. Basic authentication provides no confidentiality as values are not encrypted in any way. If you are using the Basic standard, be sure to use SSL (Secure Socket Layer). OAuth has security parameters in place that protect your data. Details about the OAuth security protocol are found at the end of this document.

Requests are made using an http GET. OAuth requests are made using an http GET along with Oauth authentication parameters.

The examples below use the Basic protocol, but OAuth uses a similar format. For Basic, the URI is /basic/rest-3.x/obsfcst.wsgi. For Oauth, use /oauth/rest-3.x/obsfcst.wsgi. More details about using OAuth can be found at the end of this document.

For specifics on the GET query parameters <weatherDataRequest> xml schema, see http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd

Example: POST request by StationID

<?xml version=’1.0′ encoding=’UTF-8′ standalone=’no’?>

<wx:weatherDataRequest

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance“

xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/“

xmlns=”http://weather.dtn.com/rest-3.4/doc/​“​

xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/​http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:dataType>DailyForecast</wx:dataType>

  <wx:dataTypeMode>0001</wx:dataTypeMode>

  <wx:startDate>2012-03-20T12:19:02Z</wx:startDate>

  <wx:endDate>2012-03-23T12:19:02Z</wx:endDate>

  <wx:locationRequestList>

      <wx:locationRequest>

        <wx:stationID>EGLL</wx:stationID>

      </wx:locationRequest>

  </wx:locationRequestList>

</wx:weatherDataRequest>

1                                                  

Example: GET request by postalAddress

http://username:[email protected]/basic/rest-3.4/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001
&startDate=2012-03-23T07%3A24%3A48.613676Z&endDate=2012-03-24T07%3A24%3A48.613676Z
&postalAddress=11400+Rupp+Dr,+Burnsville,+MN+55337-1279

The ‘postalAddress’ parameter must not have spaces in a GET request. You must replace the spaces of the address with a ‘+’ character.

Example: POST request by postalAddress

<?xml version=’1.0′ encoding=’UTF-8′ standalone=’no’?>

<wx:weatherDataRequest

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance“

xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/​” xmlns=”http://weather.dtn.com/rest-3.4/doc/“

xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/ http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:dataType>DailyForecast</wx:dataType>

  <wx:dataTypeMode>0001</wx:dataTypeMode>

  <wx:startDate>2012-03-20T12:19:02Z</wx:startDate>

  <wx:endDate>2012-03-23T12:19:02Z</wx:endDate>

  <wx:locationRequestList>

      <wx:locationRequest>

        <wx:postalAddress>11400 Rupp Dr, Burnsville, MN 55337-1279</wx:postalAddress>

      </wx:locationRequest>

  </wx:locationRequestList>

</wx:weatherDataRequest>

1                                                  

Example: GET request by Latitude/Longitude

http://username:[email protected]/basic/rest-3.4/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001

&startDate=2012-03-23T07%3A24%3A48.613676Z&endDate=2012-03-24T07%3A24%3A48.613676Z&latitude=39.1208

&longitude=-94.5969

Example: POST request by Latitude/Longitude

<?xml version=’1.0′ encoding=’UTF-8′ standalone=’no’?>

<wx:weatherDataRequest
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/“

xmlns=”http://weather.dtn.com/rest-3.4/doc/”
xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:dataType>DailyForecast</wx:dataType>

  <wx:dataTypeMode>0001</wx:dataTypeMode>

  <wx:startDate>2012-03-20T12:22:30Z</wx:startDate>

  <wx:endDate>2012-03-23T12:22:30Z</wx:endDate>

  <wx:locationRequestList>

      <wx:locationRequest>

        <wx:latitude>39.1208</wx:latitude>

        <wx:longitude>-94.5969</wx:longitude>

      </wx:locationRequest>

  </wx:locationRequestList>

</wx:weatherDataRequest>

1                                                  

Example: GET request for specific values

Specific values are requestable by including “<element name>=<unit of measure>” in the request prior to encoding (or just “<element_name>=1” if there is Unit of Measurement (uom) ).

http://username:[email protected]/basic/rest-3.4?dataType=HourlyObservation&dataTypeMode=0001
&startDate=2013-03-04T13%3A44%3A44Z&endDate=2013-03-04T14%3A44%3A44Z&latitude=44.880277
&longitude=-93.216666&cloudCoverPercentage=1&temperature=C

This XML will be returned:

<?xml version=’1.0′ encoding=’UTF-8′?>

<wx:weatherDataResponse
xmlns=”</span>http://weather.dtn.com/rest-3.4/doc/”
xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:locationResponseList>

      <wx:locationResponse>

        <wx:startDate>2014-04-30T15:44:42+00:00</wx:startDate>

        <wx:endDate>2014-05-01T15:44:42+00:00</wx:endDate>

        <wx:validDateTime>2014-04-30T16:00:00+00:00</wx:validDateTime>

        <wx:cloudCoverPercentage>

            <wx:value>100</wx:value>

        </wx:cloudCoverPercentage>

        <wx:temperature>

            <wx:value>14.1</value>

            <wx:uom>C</uom>

        </wx:temperature>

        <wx:stationID>KMSP</wx:stationID>

        <wx:stationLatitude>44.880277</wx:stationLatitude>

        <wx:stationLongitude>-93.216666</wx:stationLongitude>

      </wx:locationResponse>

  </wx:locationResponseList>

</wx:weatherDataResponse>

1                                                  

Another specific use case is whether to use metric (SI) or imperial units. For example, temperature is available in both Fahrenheit and Centigrade. If you use this request:

http://username:[email protected]/basic/rest-3.4/obsfcst.wsgi?dataType=HourlyLatestObservation
&dataTypeMode=0001&startDate=2015-03-04T16:35:23Z&endDate=2014-03-04T17:35:23Z&latitude=44.880277
&longitude=-93.216666&windChill=C

This XML will be returned:

<wx:weatherDataResponse

xmlns=”http://weather.dtn.com/rest-3.4/doc/”
xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/“

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:locationResponseList>

      <wx:locationResponse>

        <wx:startDate>2014-03-04T19:00:00Z</wx:startDate>

        <wx:endDate>2014-03-04T19:00:00Z</wx:endDate>

        <wx:validDateTime>2014-03-04T19:00:00Z</wx:validDateTime>

        <wx:country>US</wx:country>

        <wx:offset>6.0</wx:offset>

        <wx:placeName>MINNEAPOLIS</wx:placeName>

        <wx:stationID>KMSP</wx:stationID>

        <wx:stationLatitude>44.880277</wx:stationLatitude>

        <wx:stationLongitude>-93.216666</wx:stationLongitude>

        <wx:windChill>

            <wx:value>-13.9</wx:value>

            <wx:uom>C</wx:uom>

          </wx:windChill>

      </wx:locationResponse>

  </wx:locationResponseList>

</wx:weatherDataResponse>

1                                                  

In this example, windChill is set to Celsius with the “windChill=C” specification in the request above. The returned XML shows that Unit of Measurement (uom) is set to Centigrade (“C”). To use Fahrenheit, the letter “F” would be used.

To see what units are currently available for any given element, refer to the following XSD schema (http://weather.dtn.com/rest-3.4/doc/units.xsd)

Example: Request made for Historical Data

Currently, requests made with datatype ‘dailyobservation’ are limited to a start date period no earlier than 60 days in the past. A new datatype was added to rest-3.4 which allows users to make daily observation requests for data up to 2 years and even up to 5 years are accepted. Users who wish to collect data older than 60 days, must be provisioned specifically to be allowed to make such requests. Individual requests must be made for no more than 60 days at a time.

http://username:[email protected]/basic/rest-3.4/obsfcst.wsgi?dataType=DailyObservationExtended&dataTypeMode=0001
&startDate=2013-03-04T13%3A44%3A44Z&endDate=2013-04-04T14%3A44%3A44Z&latitude=44.880277
&longitude=-93.216666&cloudCoverPercentage=1&temperature=C

This XML will be returned:

<?xml version=’1.0′ encoding=’UTF-8′?>

<wx:weatherDataResponse
xmlns=”http://weather.dtn.com/rest-3.4/doc/“

xmlns:wx=”http://weather.dtn.com/rest-3.4/doc/”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=”http://weather.dtn.com/rest-3.4/doc/http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd“>

  <wx:locationResponseList>

      <wx:locationResponse>

        <wx:startDate>2013-03-04T13:44:42+00:00</wx:startDate>

        <wx:endDate>2014-04-04T14:44:42+00:00</wx:endDate>

        <wx:validDateTime>2013-03-04T16:00:00+00:00</wx:validDateTime>

        <wx:cloudCoverPercentage>

            <wx:value>100</wx:value>

            </wx:cloudCoverPercentage>

        <wx:temperature>

            <wx:value>14.1</value>

            <wx:uom>C</uom>

        </wx:temperature>

        <wx:stationID>KMSP</wx:stationID>

        <wx:stationLatitude>44.880277</wx:stationLatitude>

        <wx:stationLongitude>-93.216666</wx:stationLongitude>

      </wx:locationResponse>

  </wx:locationResponseList>

</wx:weatherDataResponse>

1                                                  

Responses

The <weatherDataResponse> XML element conforms to the service’s schema definition (at http://weather.dtn.com/rest-3.4/doc/TDTNWeatherDataService.xsd).

Each response document consists of a variable list of child elements — suitable to the requested type and mode.

If a particular data parameter is unavailable, it will be flagged as <notAvailable>. For example <precipitationAmount> for a DailyObservation request is only available at the end of the day.

postalAddress Response

The <weatherDataResponse> will contain the parameters of the request identifying the location of the weather observation or forecast.  This will be the location of the address that was requested. The response will also contain a hashed map of the location.

Data Types

Data Type Start Date End Date

HourlyLatestObservation

Not used

Not used

HourlyObservation

60 days from U.D.

Now

DailyObservation

60 days from U.D.

Now

DailyObservationExtended

2 or 5 years from U.D. (*)

Now

DailyNormal

60 days from U.D.

15 days from U.D.

HourlyForecast

1 day before U.D 15 days from U.D.

15 days from U.D.

DailyForecast

1 day before U.D 15 days from U.D.

15 days from U.D.

LatestMETAR

Not used

Not used

LatestTAF

Not used

Not used

LatestNOTAM

Not used

Not used

HourlyGriddedPrecipitation (mode 1)

Not used

Not used

HourlyGriddedPrecipitation (mode 2)

Not used

Not used

HourlyGriddedPrecipitation (mode 3)

Start of the day ** End of the day

End of day

DailyInterpolatedObservation (mode 1)

5 years from local today

Local today

DailyInterpolatedObservation (mode 2)

5 years from local today

Local today

DailyInterpolatedObservation (mode 3)

1 Jan – 1 year back

Local today ***

DailyInterpolatedObservation (mode 4)

1 Jan – 1 year back

Local today ***

DailyInterpolatedObservation (mode 5)

2013-09-01

Local yesterday

DailyInterpolatedObservation (mode 6)

2013-09-01

Local yesterday

DailyInterpolatedForecast

Local today

15 days from local today

DailyInterpolatedNormal (modes 1, 2)

Not greather than 4 years. Start and end within the year. ****

* The date range depends on the subscription (2 or 5 years). In any case, the difference between the start and end date must be at most 60 days apart the one from each other.

** Both start and end dates must be in the same local day, and has to be within the last 24 hours.

*** The trend’s requests – start date back to end date within the year, will return data for that range and “that” month/day range for the last 5 years.

**** The requests use the month and day portions of the start and end dates, the year is checked that it is not more than 4 years. These requests will return normals for the month/day range of start to end.

Data Type Modes

Enumeration ValueDataType Description

0001

HourlyLatestObservation

Single, most recent observation (may be partial) within the last 60 days.

0001

HourlyForecast

Standard hourly forecast(s) out 15 days.

0001

HourlyObservation

All sub-hourly observations over specified date range within the last 60 days.

0001

DailyForecast

Standard daily forecast(s) out 15 days.

0001

DailyObservation

Daily observation(s) within the past 60 days.

0001

DailyObservationExtended

Daily observation(s) within the past 2 years (or 5 years if provided), in 60 days pages.

0001

DailyNormal

Standard daily normal(s) within the past 60 days and out 15 days.

0001

DailyInterpolatedObservation

(RFC) Accumulated Daily Interpolated Observation(s) over specified date range, within the last five years.

0001

DailyInterpolatedNormal

Accumulated Daily Interpolated Normal(s) over specified date range, within the last five years.

0001

HourlyGriddedPrecipitation

Precipitation as measured by radar during the last 24 hours.

0001

LatestMETAR

If no METAR is available for that location no data available will be returned.

0001

LatestTAF

If no TAF is available for that location no data available will be returned.

0001

LatestNOTAM

If no NOTAM is available for that location no data available will be returned.

Enumeration Value 0001 represents the basic mode. All DataType values will have a 0001 DataTypeMode.

0002

HourlyLatestObservation

Single, most recent observation (with hourly quality controls) within the last 60 days.

0002

HourlyObservation

All observations over specified time period (with hourly quality controls) within the last 60 days.

0002

HourlyForecast

Hourly forecast(s) out 15 days from stations that also report observations.

0002

DailyForecast

Daily forecast(s) out 15 days from stations that also report observations.

0002

DailyObservation

Daily observation(s) within the past 60 days.  No values or uom if not data available.

0002

DailyObservationExtended

Daily observation(s) within the past 2 years (or 5 years if provided), in 60 days pages, from stations that also report forecasts.

0002

DailyInterpolatedObservation

(RFC) List of Daily Interpolated Observation(s) over specified date range, within the last 5 years.

0002

DailyInterpolatedForecast

List of Daily Interpolated Forecast(s) for the next 14 days.

0002

DailyInterpolatedNormal

List of Daily Interpolated Normal(s) over specified date range, within the last 5 years, using one year pages.

0002

HourlyGriddedPrecipitation

Precipitation as measured by radar since local midnight.

0002

LatestMETAR

If no METAR is available for that location, the service will return a METAR from the nearest location withing 100 NM.

0002

LatestTAF

If no TAF is available for that location, the service will return a TAF from the nearest location withing 100 NM.

0002

LatestNOTAM

If no NOTAM is available for that location, the service will return a NOTAM from the nearest location withing 100 NM.

This and further values are enhanced modes of data types and may not be valid for all DataType values.

0003

HourlyLatestObservation

Top-of-the-hour, most recent observation (with all quality controls), within the last 60 days.

0003

HourlyObservation

Top-of-the-hour, observation(s) with hourly quality controls, within the last 60 days.

0003

DailyInterpolatedObservation

List of 5 yearly, interpolated observations for the specified date range.  The start date must not be more than a year from today.

0003

HourlyGriddedPrecipitation

Precipitation as measured by radar within period (startDate – endDate).  Maximum of 24 hours.

0004

HourlyLatestObservation

Single, most recent observation (may be partial).  No values or uom if not data available.

0004

HourlyObservation

All sub-hourly observations within requested time period.  No values or uom if not data available.

0004

DailyInterpolatedObservation

List of 5 accumulated, yearly, interpolated observations for the specified date range.

0005

HourlyLatestObservation

Most recent observation (with hourly quality controls).  No values or uom if not data available.

0005

HourlyObservation

All observations within requested time period (with hourly quality controls).  No values or uom if not data available.

0005

DailyInterpolatedObservation

(MRMS) Accumulated Daily Interpolated Observation(s) over specified date range, within the last 5 years.

0006

DailyInterpolatedObservation

(MRMS) List of Daily Interpolated Observation(s) over specified date range, within the last 5 years.

Faults

When the service encounters an issue, it returns a <faultCondition> element as defined in the XSD.  Each fault condition is enumerated as an integer <faultReason> along with a human readable string describing what happened.

Refer to the XSD for fault codes (http://weather.dtn.com/rest-3.4/doc/fault.xsd).

If the start or end dates of the request falls out of the allowed date time range for each specific datatype, the service will return a fault code indicating so. Each date range is specified in the following chart.

U.D stands for Universal Day, calculated as the midnight on the International Day Line (midnight of UTC + 14).

OAuth Security

Authentication of requests is handled through usage of one of two security protocols: the OAuth standard, or the Basic standard. If you are using the Basic standard, be sure to use SSL (Secure Socket Layer) because usernames and passwords are sent as plain text. OAuth has security parameters in place that protect your data.

Weather Web Services supports OAuth 1.0 but not OAuth 2.0.

The sort order of parameters is normalized into a single string as follows (see Section 3.4.1.3.2 of the OAuth spec):

  1. The name and value of each parameter is encoded (Section 3.6).

  2. The parameters are sorted by name, using ascending byte value ordering. If two or more parameters share the same name, they are sorted by their value.

  3. The name of each parameter is concatenated to its corresponding value using an “=” character (ASCII code 61) as a separator, even if the value is empty.

  4. The sorted name/value pairs are concatenated together into a single string by using an “&” character (ASCII code 38) as separator.

Nonce and Timestamp

The timestamp value must be a positive integer and is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.

A nonce is a random string, uniquely generated by the client to allow the server to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel. The nonce value MUST be unique across all requests with the same timestamp, client credentials, and token combinations.

Signature

In order for the server to verify the authenticity of an OAuth-authenticated request and prevent unauthorized access, the client needs to prove that it is the rightful owner of the credentials. This is accomplished using the shared-secret.

The implementation provides two methods for the client to prove its rightful ownership of the credentials: “HMAC-SHA1″and “PLAINTEXT”. These methods are generally referred to as signature methods, even though “PLAINTEXT” does not involve a signature.

OAuth does not mandate a particular signature method, as each implementation can have its own unique requirements.

The client declares which signature method is used via the “oauth_signature_method” parameter. It then generates a signature (or a string of an equivalent value) and includes it in the “oauth_signature” parameter. The server verifies the signature as specified for each method.

The signature process does not change the request or its parameters, with the exception of the “oauth_signature” parameter.

Percent Encoding

Existing percent-encoding methods do not guarantee a consistent construction of the signature base string. The following percent-encoding method is not defined to replace the existing encoding methods defined by [RFC3986] and [W3C.REC-html40-19980424]. It is used only in the construction of the signature base string and the “Authorization” header field.

This specification defines the following method for percent-encoding strings:

  1. Text values are first encoded as UTF-8 octets per [RFC3629] if they are not already. This does not    include binary values that are not intended for human consumption.

  2. The values are then escaped using the [RFC3986] percent-encoding (%XX) mechanism as follows:

  • Characters in the unreserved character set as defined by [RFC3986], Section 2.3 (ALPHA, DIGIT, “-“, “.”, “_”, “~”) MUST NOT be encoded.

  • All other characters MUST be encoded.

  • The two hexadecimal characters used to represent encoded characters MUST be uppercase.

This method is different from the encoding scheme used by the “application/x-www-form-urlencoded” content-type (for example, it encodes space characters as “%20” and not using the “+” character). It MAY be different from the percent-encoding functions provided by web-development frameworks (e.g., encode different characters, use lowercase hexadecimal characters).

Signature Base String

The signature base string is a consistent, reproducible concatenation of several of the HTTP request elements into a single string. The string is used as an input to the “HMAC-SHA1” and “RSA-SHA1” signature methods.

The signature base string includes the following components of the HTTP request:

  • The HTTP request method (e.g., “GET”, “POST”, etc.).

  • The authority as declared by the HTTP “Host” request header field.

  • The path and query components of the request resource URI.

  • The sorted protocol parameters excluding the “oauth_signature”.

  • Parameters included in the request entity-body if they comply with the strict restrictions defined in Section 3.4.1.3.

The signature base string does not cover the entire HTTP request. Most notably, it does not include the entity-body in most requests, nor does it include most HTTP entity-headers. It is important to note that the server cannot verify the authenticity of the excluded request components without using additional protections such as SSL/TLS or other methods.

String Construction

The signature base string is constructed by concatenating together, in order, the following HTTP request elements:

  1. The HTTP request method in uppercase. For example: “GET” or “POST”. If the request uses a custom HTTP method, it MUST be encoded (Section 3.6).

  2. An “&” character (ASCII code 38).

  3. The base string URI from Section 3.4.1.2, after being encoded (Section 3.6).

  4. An “&” character (ASCII code 38).

  5. The request parameters as normalized in Section 3.4.1.3.2, after being encoded    (Section 3.6).

For example, the HTTP request:

POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

Authorization: OAuth realm=”Example”,

oauth_consumer_key=”9djdj82h48djs9d2″,

oauth_signature_method=”HMAC-SHA1″,

oauth_timestamp=”137131201″,

oauth_nonce=”7d8f3e4a”,

oauth_signature=”bYT5CMsGcbgUdFHObYMEfcx6bsw%3D”

1                                                  

is represented by the following signature base string.

POST&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a3%3D2%2520q%26a3%3Da%26b5%3D%253D%25253D%26c%2540%3D%26c2%3D%26
oauth_consumer_key%3D9djdj82h48djs9d2%26oauth_nonce%3D7d8f3e4a%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D137131201

Base String URI

The scheme, authority, and path of the request resource URI [RFC3986] are included by constructing an “http” or “https” URI representing the request resource (without the query or fragment) as follows:

  1. The scheme and host must be in lowercase.

  2. The host and port values must match the content of the HTTP request “Host” header field.

  3. The port must be included if it is not the default port for the scheme, and MUST be excluded if it is the default. Specifically, the port must be excluded when making an HTTP request [RFC2616] to port 80 or when making an HTTPS request [RFC2818] to port 443. All other non-default port numbers must be included.

For example, the HTTP request:

GET /r%20v/X?id=123 HTTP/1.1

Host: EXAMPLE.COM:80

is represented by the base string URI:

“http://example.com/r%20v/“.

In another example, the HTTPS request:

GET /?q=1 HTTP/1.1

Host: www.example.net:8080

is represented by the base string URI:

“https://www.example.net:8080/“.

Supported Signature Methods

Requests must be signed using HMAC-SHA1.

HMAC-SHA1

The “HMAC-SHA1” signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104]:

digest = HMAC-SHA1 (key, text)

The HMAC-SHA1 function variables are used in following way:

 

 

 

text Set to the value of the signature base string
key

Set to the concatenated values of:

  1. The client shared-secret, after being encoded.

  2. An “&” character (ASCII code 38), which MUST be included even when either secret is empty.

  3. The token shared-secret, after being encoded
digest Used to set the value of the “oauth_signature” protocol parameter, after the result octet string is base64-encoded per [RFC2045], Section6.8.

 

OAuth Requests

An authenticated request includes several parameters. Each parameter’s name and value is case sensitive. Clients make authenticated requests by calculating basic_parameter values and adding them to the HTTP request as follows:

    1. The client assigns value to each of these required protocol parameters:

      • oauth_consumer_key: The identifier portion of the client credentials equivalent to a username.

      • oauth_signature_method: The name of the signature method used by the client to sign the request, as defined in Section 3.4.

      • oauth_timestamp: The timestamp value as defined in Section 3.3.

      • oauth_nonce: The nonce value as defined in Section 3.3.

    3. The protocol parameters are added to the request using one of the transmission methods listed in Section 3.5. Each parameter must not appear more than once per request.

    4. The client calculates and assigns the value of the basic_signature parameter as described in Section 3.4 and adds the parameter to the request using the same method as in the previous step.

    5. The client sends the authenticated HTTP request to the server.

Example: GET request by StationID – (OAuth)

To request a daily forecast for the station KMSP, make the following HTTP GET request

 

Request Method GET
Request Parameter

dataType

dataTypeMode

startDate

endDate

stationID
Request URI /oauth/rest-3.4/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&startDate=2011-09-20T00:00:00Z
&endDate=2011-09-29T00:00:00Z&stationID=KMSP
Request Version HTTP/1.1

 

The client assigns values to the following protocol parameters using its client credentials, token credentials, the current timestamp, a uniquely generated nonce, and indicates that it will use the “HMAC-SHA1” signature method:

 

 

oauth_consumer_key Test
oauth_signature_method

HMAC-SHA1
oauth_timestamp 137131201
oauth_nonce 7d8f3e4a

 

The client adds the sorted protocol parameters to the request.

 

Request Method GET
Request Parameters

dataType

dataTypeMode

startDate

endDate

stationID
Request URI

/oauth/rest-3.4/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&startDate=2011-09-20T00:00:00Z

&endDate=2011-09-29T00:00:00Z&stationID=KMSP&oauth_consumer_key=Test&oauth_nonce=7d8f3e4a

&oauth_timestamp=137131201&oauth_signature_method=HMAC-SHA1
Request Version HTTP/1.1

 

Then, it calculates the value of the “oauth_signature” parameter, adds it to the request, and sends the HTTP request to the server:

 

Request Method GET
Request Parameter

dataType

dataTypeMode

startDate

endDate

stationID
Request URI /oauth/rest-3.4/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&startDate=2011-09-20T00:00:00Z&endDate=2011-09-29T00:00:00Z&stationID=KMSP &oauth_consumer_key=Test&oauth_nonce=7d8f3e4a&oauth_timestamp=137131201&oauth_signature_method=HMAC-SHA1&oauth_signature=bYT5CMsGcbgUdFHObYMEfcx6bsw%3D
Request Version HTTP/1.1

 

Category: REST Service, Web Services