previous   next   contents   top

Cast-to-Met HTTP

This document describes the HTTP protocol as used specifically by Metcast. See a brief HTTP 1.1 protocol reference for a general description of HTTP.
    Contents
  1. Making a request
    1. Request method
    2. Request URI
    3. Request message headers
  2. Server Response
    1. Status Code
    2. Response message headers
    3. Response Body
  3. Authorization and Access Authentication
  4. Sample client-server transactions
  5. Sending reply over e-mail

   

Request protocol

A request from a Metcast client to a server is a standard HTTP message
start-line (request-line)
Method SP Request-URI SP HTTP/1.0 CRLF
header fields (headers)
an empty line
a line with nothing preceding the CRLF indicating the end of the header fields
a message-body
that tells specifically the area of interest, which products are being asked for, preferred databases, etc. Metcast application-specific information. In some request messages (for example, the ones that ask about the status of a previous request), the message body can be absent.

 

Request method

Can be either GET or POST. In limited circumstances, when the user wants only updates from a standard area, he may use GET method. Normally, use POST.


 

Request URI

must be an absolute URI (especially when the request is being made to a proxy)


 

Request message headers

The request-header fields allow the client to pass additional information about the request, and about the client itself, to the server. These fields act as request modifiers, with semantics equivalent to the parameters on a programming language method invocation. The headers follow the standard headers format.

Normally a few headers always have to be specified.


 

Accept

A mandatory header, which tells the server the format the client wants to receive reply in. Possible values include text/x-packed-dat, text/x-syn. In version 1.0, only text/x-packed-dat is expected.


Authorization

Provided by the client if the user wants to authenticate himself to the server. See Authorization and Authentication for more details.
     Authorization: Basic Y2xhbXM6Y2hvd2Rlcg==


Content-Length

A mandatory header if the request is done via the POST method. The header specifies the size of the request message body in bytes.


Content-Type

A mandatory header if the request is done via the POST method. The header tells what exactly request's message body is. Acceptable values are: text/x-request-mfr, application/octet-stream ??


Etag

This header will be mandatory in the version 2.0, when F*.dat files would be delievered. The header tells area's tags: full and short (folder) names, area's id, grid spacing and projection.


From

This header may be specified to give an e-mail address of a human controlling the Metcast client. The header must be specified if the client requested an asynchronous delivery of requested data.
     From: user@us.navy.mil


Host

A mandatory header, which tells the server which name it is called upon, and on which port. This header is especially important for multihoming/virtual servers. For example:
     Host: nites-2

     Host: 10.10.10.202:80


Cookie


If-Modified-Since

This header is mandatory in a request for an update (for example, a request to deliver new METAR observations, the ones that arrived after a specified time). This header tells the base time to gather updates from, in the the standard HTTP datetime format. For example, 
     If-Modified-Since: Thu, 01 Dec 1994 16:00:00 GMT


Range

This header will be mandatory in version 2.0. It should tell the bounding box for an area on the globe for which data are requested. ??
     Range: lats=; lons=100-120 "10.0N 20.0S 100.1E 120W"


If-Match

See Etag 
     If-Match: "xyzzy" area dimensions?


Pragma

??
     Pragma: token [ "=" ( token | quoted-string ) ]


User-Agent

A mandatory header that tells the name and the version of the client.



   

Server Response

After receiving and interpreting a request message, a Metcast server responds with an HTTP response message, which is a standard HTTP message, made of
Status-Line
HTTP/1.0 SP Status-Code SP Reason-Phrase CRLF
The first line of a response message is the Status-Line, consisting of the protocol version followed by a numeric status code and its associated textual phrase, with each element separated by SP characters. No CR or LF is allowed except in the final CRLF sequence.
header fields (headers)
an empty line
a line with nothing preceding the CRLF indicating the end of the header fields
an optional message-body

 

Status Code

The full set of status codes is defined in the HTTP standard. Given below is a subset a Metcast client must recognize and process. For any other status code, the client has to simply display the code and the accompanying message. In addition, when a 4xx or 5xx status code is received, the user ought to be alerted of an error.


Status code 200: OK

The request succeeded. The requested data (products) are contained in the response message body

Status code 202: Accepted

The server accepted the request and initiated the processing, but the processing has not been completed. The result will be sent asynchronously (via e-mail?) ??

Status code 204: No Content

The server has fulfilled the request but there is no new information to send back. ??

Status code 304: Not Modified

No new information (in a request for an update). This response contains no message body.

 

Status code 401:Unauthorized

Means that the server refused to accept the request because the client failed to submit proper credentials (or failed to submit any).
A browser is usually requried to analyze the WWW-Authenticate header that must be present in the present response, ask the user for more credentials, and repeat the request with the proper Authorization header; see section 10.4.2 of the standard
We, however, don't do all that: if access is denied, the user is told so, and that is it; see the authorization section for more details.

 

Response message headers

They headers follow the standard headers format and tell information about the format, size and other attributes of the response data (or some conditions the server had come across while fulfilling the request).

Content-Length

Always present if the reply carries a message body. The header specifies the size of the response message body in bytes.


Content-Type

Always present if the reply carries a message body. The header tells what exactly response's message body is. The type is usually one of the values the client requested in the Accept request header, and usually parameterized with the area name etc. parameters as approriate.
     Content-Type: text/x-packed-dat; AREA="NORF"

Note, the reply can be a multipart message, and can be encoded/compressed, see Content-Encoding and Transfer-Encoding


Content-Encoding

A server may want to encode/compress the response body (grids, observations, etc). Possible values are: gzip, compress (UNIX compress) and deflate (zlib/pkzip)??. The client must be prepared to perform decoding/decompression of the body.


Etag

This header will be mandatory in the version 2.0, when F*.dat files would be delivered. The header tells area's tags: full and short (folder) names, area's id, grid spacing and projection. Should it rather be a parameter of the Content-Type??


Cookie


Date

Always present: tells the date and time when the response has been generated, in the the standard HTTP date format. Note, it is the time of the response, which is not identical to the time when data (grid products) were retrieved from the database: the server may have cached data from the database. To find out product's valid time, refer to Expires or Last-Modified headers.
     Date: Tue, 15 Nov 1994 08:12:31 GMT


Expires

May be present, to tell the moment after which data are to be considered stale (invalid), in the the standard HTTP date format. If the moment in this header points to some date in the future, any gateway/intermediary may cache this response (unless specifically prohibited by cache control headers).


Last-modified

May be present in the response to tell the client when the server believes the product/grids/etc returned in this response were last modified, in the the standard HTTP date format.
     Last-Modified: Thu, 01 Dec 1994 16:00:00 GMT


Retry-After

The Retry-After response-header field can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable to the requesting client. The value of this field can be either an HTTP-date or an integer number of seconds (in decimal) after the time of the response. 

     Retry-After  = "Retry-After" ":" ( HTTP-date | delta-seconds )

Two examples of its use are
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120
In the latter example, the delay is 2 minutes.


Pragma

Tells the e-mail address??
     Pragma: token [ "=" ( token | quoted-string ) ]


Server

Always present: tells the name and the version of the Metcast server that has generated this reply


Transfer-Encoding

May be present to specify an additional encoding imposed by the transport. Usually present when binary data are to be sent via e-mail.


 

Response Body

is a MIME message containing the requested product, or products. In the latter case, the response message is a composite (multi-part) message, containing as many entities as there are separate products in the reply. The Content-Type response header specifies the kind of the weather product the message carries, and additional parameters (e.g., description of a product). If the message is multi-part, then Content-Type is set to "multipart/mixed"; each separate entity of the multipart message has its own set of headers describing its content, including Content-Type and possibly Content-Length, Content-Encoding, etc.

If Content-Encoding or Transfer-Encoding response headers are present, the response body is compressed and encoded.

For more details on handling of the response message, see the description of the Metcast client, retriever.

   

Authorization and Access Authentication

We keep to the HTTP standard , with the following simplification:

If the user specified that it wants to authenticate itself to the server (by checking a special option in JMV shell's Options panel, and supplying an id and the password), the retriever module computes the basic authorization credential and submits it with the request, in the Authorization header.

In any case, if the server replies with 401 (Unauthorized) message, the access has been denied, and that is final. We simply log the whole response (which may contain some explanation why access was denied), and quit.

Just for the reference, here is an example of browser-server interaction, when a Netscape browser tried to GET a resource whose access was limited (by an .htaccess file).

The client (browser) opens the connection and submits the request: 

GET /resourse/ HTTP/1.0
Connection: Keep-Alive
User-Agent: Mozilla/3.0 (Macintosh; I; 68K)
Host: 10.10.10.202:4001
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
[An empty line]
The server replies:
HTTP/1.0 401 Unauthorized
Server: Netscape-Communications/1.12
Date: Tuesday, 11-Feb-97 00:30:41 GMT
WWW-authenticate: basic realm="Earls Clams"
Content-type: text/html
Content-length: 223

<HTML><HEAD><TITLE>Unauthorized</TITLE></HEAD>
<BODY><H1>Unauthorized</H1>
Proper authorization is required for this area. Either your browser
does not perform authorization, or your authorization has failed.
</BODY></HTML>
and closes the connection.

The (Netscape) browser displays a dialog asking the user to enter an id and a password. After that, the browser opens the connecton again and resubmits the request, this time including the Authorization header: 

GET /resource/ HTTP/1.0
Connection: Keep-Alive
User-Agent: Mozilla/3.0 (Macintosh; I; 68K)
Host: 10.10.10.202:4001
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Authorization: Basic Y2xhbXM6Y2hvd2Rlcg==
[An empty line]
The authorization was invalid, and the server simply closed the connection. Obviously the server was too rude (or obsolete): it should have sent the 401 response again.

   

Sample client-server transactions

Requesting a single product

POST http://nites-2/cgi-bin/server HTTP/1.0
Accept: text/x-packed-dat
Host: nites-2
Content-Length: 100
Content-Type: text/x-request-mfr
User-Agent: JMV/1.8

NORF
CURRENTDTG    JMV 1.7.0f 19961025
1
96CC011NOG A01 45.000N 099.000W 024 023 026 01.0 001.0OM


Reply

HTTP/1.0 200 OK
Server: Netscape-Communications/1.12
Date: Tuesday, 21-Jan-97 23:57:25 GMT
Last-modified: Tuesday, 21-Jan-97 23:17:59 GMT
Content-length: 1841
Content-type: text/x-packed-dat; AREA="NORF"

PACKED.DAT 97012000
METXA01 00242000 9701
MSGID/FNOC/GRIDFLD/0001/JAN
PROD/OCEANMET/200000Z2/JAN/024/1OF1/A01 NOGAPS
GRID/4500N9/09900W8//026/023//1.00DEG/1.00DEG//08
CMPCT/BS1/0.10103E 04/0.14474E-01
NARR/24 HR FCST FM 00Z 20JAN97
KTOSROUDW0Y60P1I1U2C293P2W1S040CYXWYUHRDM0JVG2DLBLAAJJMOQTTMV7Z8Z8Z8
YDZW0016293V3K2P1X1H0QY1WLTQQXOHKZH3EACJBUHTK2PSSSU6W9YZ0H1V2V8G8G8G
....
VU3A7X1Y4U6B9WAC34DOD1EYAL5AZWY2ZLXPWZRSQVVUXRZRTVWU9IGPKCBMGRVTVTVT
ENDAT
END OF DOWNLOAD


Requesting several products

POST http://nites-2/cgi-bin/server HTTP/1.0
Accept: text/x-packed-dat; text/x-syn
Host: nites-2
Content-Length: 332
Content-Type: text/x-request-mfr
User-Agent: JMV/1.8

BIG area
CURRENTDTG    JMV 1.8.Xa
4 
973EC11XXX SYN 80.000N 025.000W 000 235 393 00.5 000.5OM
973EC11XXX MZZ 80.000N 025.000W 000 025 041 05.0 005.0OM
973EC12NOG A01 79.000N 022.500W 000 079 133 01.5 001.5OM
973EC22NOG A01 39.000S 022.500W 000 001 133 01.5 001.5OM
976AC13XXX SVN 0    1 9999 9999 105050000 0000 0000 0000 0000000B


Reply

HTTP/1.0 200 OK
Server: Netscape-Communications/1.12
Date: Tuesday, 21-Jan-97 23:57:25 GMT
Content-Type: multipart/mixed; boundary="boundary-JMVVMJ yradnuob"

--boundary-JMVVMJ yradnuob
Content-type: text/x-syn; area="BIGAREA"
Content-length: 193

   DGAA   5.6   -0.2***************************************11
5 METAR 560 -16 871488000 871495200 654720 DGAA  ACCRA/KOTOKA INTL
METAR DGAA 131600Z 23008KT 9999 FEW018 BKN120 27/22 Q10//
--boundary-JMVVMJ yradnuob
Last-modified: Tuesday, 21-Jan-97 23:17:59 GMT
Content-type: image/x-portable-graymap; AREA="BIGAREA"; KIND="SVN";
      Description="North Atlantic Satellite (VIS)"; TIMESTAMP=871056746

P5
800 800
255
JJ...sat-data...
--boundary-JMVVMJ yradnuob
Content-type: text/x-packed-dat; area="BIGAREA"
Last-modified: Tuesday, 21-Jan-97 23:17:59 GMT
Content-length: 1841

PACKED.DAT 97012000
METXA01 00242000 9701
	...etc...
ENDAT
END OF DOWNLOAD
Also of note... 
Content-Encoding: gzip
Content-Length: 3495
Date: Wed, 15 Nov 1995 06:25:24 GMT
      Expires: Thu, 01 Dec 1994 16:00:00 GMT

HTTP/1.1 206 Partial content
       Date: Wed, 15 Nov 1995 06:25:24 GMT
       Last-modified: Wed, 15 Nov 1995 04:58:08 GMT
       Content-Range: bytes 21010-47021/47022
       Content-Length: 26012
       Content-Type: image/gif

   

Sending reply over e-mail

Transfer Codings

 

History

$Id: Met-Cast-HTTP.html,v 3.1 2003/10/07 04:24:02 oleg Exp oleg $