MxVision WeatherSentry®
Web Services
REST Programming Guide
DTN
11400 Rupp Drive
Minneapolis, MN 55337
00.1.952.890.0609
© Copyright 2014 DTN. All rights reserved.
This document and the software it describes are copyrighted with all rights reserved. Neither this
document nor the software may be copied in whole or in part without the prior written consent of
the copyright owner. Printed in the United States of America.
DTN is a registered trademark and the property of DTN. All rights reserved.
All other trademarks are the properties of their respective owners.
2
Copyright 2014 DTN. All rights reserved.
Table of Contents
1
Introduction ............................................................................................................ 4
1.1
Terminology........................................................................................................ 4
1.2
References ......................................................................................................... 4
1.3
Release Management ........................................................................................ 5
2
Requests................................................................................................................ 6
2.1
Example: GET request by StationID - (OAuth explained).................................... 7
2.2
Example: POST request by StationID ................................................................. 8
2.3
Example: GET request by postalAddress ........................................................... 8
2.4
Example: POST request by postalAddress ......................................................... 9
2.5
Example: GET request by Latitude/Longitude..................................................... 9
2.6
Example: POST request by Latitude/Longitude .................................................. 9
2.7
Example: GET request for specific values ........................................................ 10
3
Responses ........................................................................................................... 13
3.1
postalAddress Response ................................................................................. 13
3.2
Faults ............................................................................................................... 13
4
Security ................................................................................................................ 14
4.1
Nonce and Timestamp...................................................................................... 14
4.2
Signature .......................................................................................................... 15
4.3
Percent Encoding ............................................................................................. 15
4.3.1
Signature Base String................................................................................ 16
4.3.2
String Construction .................................................................................... 17
4.3.3
Base String URI ......................................................................................... 17
4.4
4.4.1
Supported Signature Methods .......................................................................... 18
HMAC-SHA1 ............................................................................................. 18
3
Copyright 2014 DTN. All rights reserved.
1 Introduction
MxVision 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 one of two standards:
REST or SOAP.
This document is intended for those who wish to implement a REST-ful client.
If you prefer to use a SOAP client, refer to
http://weather.telventdtn.com/soap/.
1.1
Terminology
REST
SOAP
Server
OAuth
Client
Credentials
Nonce
1.2
Representational State Transfer
Simple Object Access Protocol
DTN’s MxVision WeatherSentry® (REST) Web Service
An open protocol standard which allows secured API authorization
in a simple and standard method from desktop and web
applications.
An HTTP client capable of making OAuth requests.
A unique username and password pair.
An arbitrary number used only once to sign a cryptographic
communication.
References
Web Services Architecture (REST) http://www.w3.org/TR/wsareqs/#REST
The OAuth 1.0 Protocol
http://tools.ietf.org/html/rfc5849
4
Copyright 2014 DTN. All rights reserved.
1.3
Release Management
The current documentation can be found at http://weather.dtn.com/rest-3.x;
where ‘x’ is the number of the minor release. For example, to find the
documentation for rest-3.1, use link http://weather.dtn.com/rest-3.1.
The current software release will be linked to through the above web page.
As features and enhancements are added, new revisions will become
available. We will release revisions in two categories, major and minor. Major
revisions are not guaranteed to be backward compatible, while minor revisions will
be compatible within their major revision.
All revisions may be referenced by using http://weather.dtn.com/rest-{X}.{Y} where
{X} is the major revision number and {Y} is the minor revision number. (e.g.
http://weather.dtn.com/rest-3.2)
Only the two latest major revisions are supported at any given time.
Therefore, when a major revision is released, the link to the oldest major revision
will no longer be supported and may be removed.
For example: Version 2.x and 3.x currently exist. With the release of version
4.0 all links to version 2.x will be removed and no longer supported.
5
Copyright 2014 DTN. All rights reserved.
2 Requests
Requests are made of the service using either an http GET along with OAuth
authentication parameters.
The URI is always “/oauth/rest-3.x/obsfcst.wsgi”.
For specifics on the GET query parameters <weatherDataRequest> xml
schema, see: http://weather.dtn.com/rest-3.x/doc/TDTNWeatherDataService.xsd
An authenticated request includes several parameters. Each parameter’s name
and value is case sensitive. Clients make authenticated requests by calculating
oauth_ 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.
2. 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.
3. The client calculates and assigns the value of the "oauth_signature"
parameter as described in Section 3.4 and adds the parameter to the
request using the same method as in the previous step.
4. The client sends the authenticated HTTP request to the server.
6
Copyright 2014 DTN. All rights reserved.
2.1
Example: GET request by StationID - (OAuth explained)
To request a daily forecast for the station KMSP. Make the following HTTP GET
request
Request Method: GET
Request URI: /oauth/rest3.2/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&st
artDate=2011-09-20&endDate=2011-09-29&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:
oauth_signature_method:
oauth_timestamp:
oauth_nonce:
Test
HMAC-SHA1
137131201
7d8f3e4a
The client adds the sorted protocol parameters to the request.
Request Method: GET
Request URI: /oauth/rest3.2/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode&00
01&startDate=2011-09-20&endDate=2011-09-29&stationID=K
MSP&oauth_consumer_key=Test&oauth_nonce=7d8f3e4a&o
auth_timestamp=137131201&oauth_signature_method=HMA
C-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 URI: oauth/rest7
Copyright 2014 DTN. All rights reserved.
3.2/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=00
01&startDate=2011-09-20&endDate=2011-09-29&stationID=K
MSP&oauth_consumer_key=Test&oauth_nonce=7d8f3e4a&o
auth_timestamp=137131201&oauth_signature_method=HMA
C-SHA1&oauth_signature=bYT5CMsGcbgUdFHObYMEfcx6b
sw%3D
Request Version: HTTP/1.1
2.2
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.2/doc/"
xmlns="http://weather.dtn.com/rest-3.2/doc/"
xsi:schemaLocation="http://weather.dtn.com/rest-3.2/doc/
http://weather.dtn.com/rest-3.2/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:weatherDataRequest>
2.3
Example: GET request by postalAddress
http://weather.dtn.com/oauth/rest3.2/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&startDate=2012
-03-23T07%3A24%3A48.613676Z&endDate=2012-03-24T07%3A24%3A48.6136
76Z&postalAddress=11400+Rupp+Dr,+Burnsville,+MN+55337-1279&oauth_cons
umer_key=Test&oauth_nonce=MHgxLmFjN2I1ZDY4ZThkNTBwLTE%3D&oauth_
signature_method=HMAC-SHA1&oauth_timestamp=1332246288&oauth_signatur
e=F0LcHxCdlAAP6kcbKgnYHeDXj54%3D
8
Copyright 2014 DTN. All rights reserved.
Note: The ‘postalAddress’ parameter must not have spaces in a GET request.
You must replace the spaces of the address with a ‘+’ character.
2.4
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.2/doc/"
xmlns="http://weather.dtn.com/rest-3.2/doc/"
xsi:schemaLocation="http://weather.dtn.com/rest-3.2/doc/
http://weather.dtn.com/rest-3.2/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:weatherDataRequest>
2.5
Example: GET request by Latitude/Longitude
http://weather.dtn.com/oauth/rest3.2/obsfcst.wsgi?dataType=DailyForecast&dataTypeMode=0001&startDate=2012
-03-23T07%3A24%3A48.613676Z&endDate=2012-03-24T07%3A24%3A48.6136
76Z&latitude=39.1208&longitude=-94.5969&oauth_consumer_key=Test&oauth_n
once=MHgxLmFjN2I1ZDY4ZThkNTBwLTE%3D&oauth_signature_method=HMA
C-SHA1&oauth_timestamp=1332246288&oauth_signature=F0LcHxCdlAAP6kcbK
gnYHeDXj54%3D
2.6
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.2/doc/"
9
Copyright 2014 DTN. All rights reserved.
xmlns="http://weather.dtn.com/rest-3.2/doc/"
xsi:schemaLocation="http://weather.dtn.com/rest-3.2/doc/
http://weather.dtn.com/rest-3.2/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>
2.7 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://weather.dtn.com/oauth/rest3.2?dataType=HourlyObservation&dataTypeMode=0001&startDate=2013-0304T13%3A44%3A44Z&endDate=2013-0304T14%3A44%3A44Z&latitude=44.880277&longitude=93.216666&cloudCoverPercentage=1&temperature=C&oauth_consumer_key=3D
Test&oauth_nonce=MHgxLmIzNzJhNmRiMDkxMGVwLTI%3D&oauth_sign=ture_
method=HMACSHA1&oauth_timestamp=1362408284&oauth_signatu=e=JypKYJHgaF2j874ak18
%2BU6G9u7I%3D
This XML will be returned:
<?xml version='1.0' encoding='UTF-8'?>
<wx:weatherDataResponse xmlns="http://weather.dtn.com/rest-3.2/doc/"
xmlns:wx="http://weather.dtn.com/rest-3.2/doc/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://weather.dtn.com/rest-3.2/doc/
http://weather.dtn.com/rest-3.2/doc/TDTNWeatherDataService.xsd">
<wx:locationResponseList>
<wx:locationResponse>
<wx:startDate>2014-04-30T15:44:42+00:00</wx:startDate>
10
Copyright 2014 DTN. All rights reserved.
<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>
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://weather.dtn.com/oauth/rest3.2/obsfcst.wsgi?dataType=HourlyLatestObservation&dataTypeMode=0001&start
Date=2014-03-04T16:35:23Z&endDate=2014-0304T17:35:23Z&latitude=44.880277&longitude=93.216666&windChill=C&oauth_consumer_key=TestSoap&oauth_nonce=MHgxLj
Y5ZDU4NjUyMjYyMWJwLTE=&oauth_signature_method=HMACSHA1&oauth_timestamp=1393954523&oauth_signature=KPXISm4+EQ1q4KDNL
uBksnCU9ZQ=
This XML will be returned:
<wx:weatherDataResponse
xmlns="http://weather.dtn.com/rest-3.2/doc/"
xmlns:wx="http://weather.dtn.com/rest-3.2/doc/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://weather.dtn.com/rest-3.2/doc/
http://weather.dtn.com/rest-3.2/doc/TDTNWeatherDataService.xsd">
<wx:locationResponseList>
<wx:locationResponse>
11
Copyright 2014 DTN. All rights reserved.
<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>
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, please refer to the
following XSD schema (http://weather.dtn.com/rest-3.2/doc/units.xsd)
12
Copyright 2014 DTN. All rights reserved.
3 Responses
The <weatherDataResponse> XML element conforms to the service’s
schema definition (at http://weather.dtn.com/rest3.2/doc/TDTNWeatherDataService.xsd).
Each response document consists of a variable list of child elements -suitable to the requested type and mode. See also Content Guide on the website
and the XSD.
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.
3.1
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.
3.2
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.
13
Copyright 2014 DTN. All rights reserved.
4 Security
Authentication of requests is handled through usage of the OAuth standard.
NOTE: It is essential that OAuth parameters listed in Section 3 are
provided in the same order when calculating a signature and in the URL.
NOTE: 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. First, the name and value of each parameter are 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.
4.1
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.
14
Copyright 2014 DTN. All rights reserved.
4.2
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.
4.3
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.
15
Copyright 2014 DTN. All rights reserved.
•
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).
4.3.1 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.
16
Copyright 2014 DTN. All rights reserved.
4.3.2 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"
is represented by the following signature base string.
POST&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a
3%3D2%2520q%26a3%3Da%26b5%3D%253D%25253D%26c%2540%3
D%26c2%3D%26oauth_consumer_key%3D9djdj82h48djs9d2%26oauth_n
once%3D7d8f3e4a%26oauth_signature_method%3DHMAC-SHA1%26oau
th_timestamp%3D137131201
4.3.3 Base String URI
17
Copyright 2014 DTN. All rights reserved.
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/X".
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/".
4.4
Supported Signature Methods
Requests must be signed using HMAC-SHA1.
4.4.1 HMAC-SHA1
The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature algorithm
as defined in [RFC2104]:
digest = HMAC-SHA1 (key, text)
18
Copyright 2014 DTN. All rights reserved.
The HMAC-SHA1 function variables are used in following way:
text
is set to the value of the signature base string
key
is 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 is used to set the value of the "oauth_signature" protocol
parameter, after the result octet string is base64-encoded per
[RFC2045], Section 6.8.
19
Copyright 2014 DTN. All rights reserved.