Programming with the WeatherSentry® REST Service

Version 43

     

    Reference : Overview - WeatherSentry® API REST Service

    Introduction

     

    WeatherSentry Web Services from Schneider Electric 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.

     

    Back to top

     

    XSD's

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

     

    Terminology

     

    ClientAn HTTP client capable of making requests.
    CredentialsA unique username and password pair.
    NonceAn arbitrary number used only once to sign a cryptographic communication.
    OAuthAn open protocol standard that allows secured API authorization in a simple and standard method from desktop and web applications.
    RESTRepresentational State Transfer
    ServerSchneider Electric’s WeatherSentry (REST) Web Service

     

    References

     

    Back to top

     

    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>
                                                       

     

    Example: GET request by postalAddress

     

    http://username:password@weather.dtn.com/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>
                                                       

    Example: GET request by Latitude/Longitude

     

    http://username:password@weather.dtn.com/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>
                                                       

     

    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:password@weather.dtn.com/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>
                                                       

     

    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:password@weather.dtn.com/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>
                                                       

     

    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:password@weather.dtn.com/basic/rest-3.4?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>
                                                       

     

    Back to top

     

    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.

     

    Back to top

     

    Data Types

     

    Data typeStart dateEnd date
    HourlyLatestObservationNot usedNot used
    HourlyObservation60 days from U.D.Now
    DailyObservation60 days from U.D.Now
    DailyObservationExtended2 or 5 years from U.D. (*)Now
    DailyNormal60 days from U.D.15 days from U.D.
    HourlyForecast1 day before U.D 15 days from U.D.15 days from U.D.
    DailyForecast1 day before U.D 15 days from U.D.15 days from U.D.
    LatestMETARNot usedNot used
    LatestTAFNot usedNot used
    LatestNOTAMNot usedNot used
    HourlyGriddedPrecipitation (mode 1)Not usedNot used
    HourlyGriddedPrecipitation (mode 2)Not usedNot used
    HourlyGriddedPrecipitation (mode 3)Start of the day ** End of the dayEnd of day
    DailyInterpolatedObservation (mode 1)5 years from local todayLocal today
    DailyInterpolatedObservation (mode 2)5 years from local todayLocal today
    DailyInterpolatedObservation (mode 3)1 Jan – 1 year backLocal today ***
    DailyInterpolatedObservation (mode 4)1 Jan – 1 year backLocal today ***
    DailyInterpolatedObservation (mode 5)2013-09-01Local yesterday
    DailyInterpolatedObservation (mode 6)2013-09-01Local yesterday
    DailyInterpolatedForecastLocal today15 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.

     

    Back to top

     

    Data Type Modes

     

    Enumeration ValueDataTypeDescription
    0001HourlyLatestObservationSingle, most recent observation (may be partial) within the last 60 days.
    0001HourlyForecastStandard hourly forecast(s) out 15 days.
    0001HourlyObservationAll sub-hourly observations over specified date range within the last 60 days.
    0001DailyForecastStandard daily forecast(s) out 15 days.
    0001DailyObservationDaily observation(s) within the past 60 days.
    0001DailyObservationExtendedDaily observation(s) within the past 2 years (or 5 years if provided), in 60 days pages.
    0001DailyNormalStandard daily normal(s) within the past 60 days and out 15 days.
    0001DailyInterpolatedObservation(RFC) Accumulated Daily Interpolated Observation(s) over specified date range, within the last five years.
    0001DailyInterpolatedNormalAccumulated Daily Interpolated Normal(s) over specified date range, within the last five years.
    0001HourlyGriddedPrecipitationPrecipitation as measured by radar during the last 24 hours.
    0001LatestMETARIf no METAR is available for that location no data available will be returned.
    0001LatestTAFIf no TAF is available for that location no data available will be returned.
    0001LatestNOTAMIf 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.
    0002HourlyLatestObservationSingle, most recent observation (with hourly quality controls) within the last 60 days.
    0002HourlyObservationAll observations over specified time period (with hourly quality controls) within the last 60 days.
    0002HourlyForecastHourly forecast(s) out 15 days from stations that also report observations.
    0002DailyForecastDaily forecast(s) out 15 days from stations that also report observations.
    0002DailyObservationDaily observation(s) within the past 60 days.  No values or uom if not data available.
    0002DailyObservationExtendedDaily observation(s) within the past 2 years (or 5 years if provided), in 60 days pages, from stations that also report forecasts.
    0002DailyInterpolatedObservation(RFC) List of Daily Interpolated Observation(s) over specified date range, within the last 5 years.
    0002DailyInterpolatedForecastList of Daily Interpolated Forecast(s) for the next 14 days.
    0002DailyInterpolatedNormalList of Daily Interpolated Normal(s) over specified date range, within the last 5 years, using one year pages.
    0002HourlyGriddedPrecipitationPrecipitation as measured by radar since local midnight.
    0002LatestMETARIf no METAR is available for that location, the service will return a METAR from the nearest location withing 100 NM.
    0002LatestTAFIf no TAF is available for that location, the service will return a TAF from the nearest location withing 100 NM.
    0002LatestNOTAMIf 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.
    0003HourlyLatestObservationTop-of-the-hour, most recent observation (with all quality controls), within the last 60 days.
    0003HourlyObservationTop-of-the-hour, observation(s) with hourly quality controls, within the last 60 days.
    0003DailyInterpolatedObservationList of 5 yearly, interpolated observations for the specified date range.  The start date must not be more than a year from today.
    0003HourlyGriddedPrecipitationPrecipitation as measured by radar within period (startDate - endDate).  Maximum of 24 hours.
    0004HourlyLatestObservationSingle, most recent observation (may be partial).  No values or uom if not data available.
    0004HourlyObservationAll sub-hourly observations within requested time period.  No values or uom if not data available.
    0004DailyInterpolatedObservationList of 5 accumulated, yearly, interpolated observations for the specified date range.
    0005HourlyLatestObservationMost recent observation (with hourly quality controls).  No values or uom if not data available.
    0005HourlyObservationAll observations within requested time period (with hourly quality controls).  No values or uom if not data available.
    0005DailyInterpolatedObservation(MRMS) Accumulated Daily Interpolated Observation(s) over specified date range, within the last 5 years.
    0006DailyInterpolatedObservation(MRMS) List of Daily Interpolated Observation(s) over specified date range, within the last 5 years.

     

    Back to top

     

    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).

     

    Back to top

     

    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"

                                                      

    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:

     

    textSet 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
    digestUsed 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.
      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 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.
      4. 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 MethodGET
    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
    Request VersionHTTP/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_keyTest
    oauth_signature_methodHMAC-SHA1
    oauth_timestamp137131201
    oauth_nonce7d8f3e4a

     

    The client adds the sorted protocol parameters to the request.

    Request MethodGET
    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 VersionHTTP/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 MethodGET
    Request Parameters

    dataTypet

    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 VersionHTTP/1.1

     

    Back to top