GDS Technical Overview
Goto: Documentation Home
To ensure maximum interoperability and simplified handling for implementing systems the rules by which data is passed between systems is clearly defined.
Integers | Character Strings | Dates
The GNAP protocol uses a standard URL path on GDS Servers, with the majority of request parameters encoded in the request part of the URL. All GDS transactions have a 4 character (A-Z,0-9) transaction code, which is applied after the URL stem of "/GNAP". So to request the BUCK transaction, the formed URL is "/GNAP/BUCK". The /GNAP part should be in uppercase, but servers will accept mixed case, but the BUCK part must be in uppercase.
From the base URL, various conversions and translations can be applied. A transction such as "BUCK" is processed by a generic handler, and these handlers only interface in the binary form of the GNAP protocol, they have no explicit knowledge of the client or how you want the data returned. Therefore you can extend the URL /GNAP/BUCK to include various request options that alter the format of the input and output to this transaction handler, but without the handler actually needing to be involved.
When requesting /GNAP transctions over HTTP link (such as from a browser), the default return format is simplified XML. You can insert a 'Reply Type' conversion between the /GNAP and /BUCK (or whatever transaction you are using) to convert the binary XML format to a format you prefer.
| URL | Format/Effect |
| /GNAP/BUCK | System selected default, which is XML for requests using HTTP on a TCP link |
| /GNAP/x/BUCK | Select XML format response |
| /GNAP/e/BUCK | Select extended XML format, where subpackets are named using an extended format, which can be easier to use in some languages |
| /GNAP/j/BUCK | Select JSON encoded response. There is also a JSON-P response format, described later. (See 'o' request format)
Not all requests can be converted to JSON in a useable form, but this is very rare within GDS transactions, and generally only advanced information (such as decoding time based audit records) that is affected. The problem is that some GNAP data packets contain information in time sequence with variable number of fields, which cannot be represented by the GNAP to JSON convertor. This restriction is unlikely to affect any normal business level requirement. |
| /GNAP/t/BUCK | Select Text response format. This format is not fully specified and should be avoided as the result output may change without warning. |
| /GNAP/b/BUCK | Explicitly request GNAP binary format. This might be used by an application (not a browser) that is consuming GNAP data. The result from the transaction handler is sent using the HTTP Content-Type of application/octet-stream. |
| /GNAP/o/BUCK | Extended Options format. This format allows you to specify additional processing arguments beyond what can be given using a single letter as the above options are using. |
The 'o' (for Options) format allows you to specify many more arguments to the formating process. The URL format is /GNAP/o/[arguments]/BUCK
| Argument | Format/Effect |
| [mkh,NNN] | Extract the field# NNN from the transaction response, and send that as a complete HTML webpage. mhk is short for "MaKe Html". This is useful where the GNAP transaction returns a complete HTML page in the response. The HTML is not altered from what is contained in the field, no headers or wrappers are applied to the output other than what is already in the transaction response. |
| [jp,NNN] | Convert the response to a format that can be used by JSON-P callback formats. This format is not yet fully specified, however using the form [jp] with no additional parameters will always result in the callback function jp100() being called. |
Where data is held in a multi host system, such that the server can apply the transaction to different input databases, the database itself will have a URL prefix stem, to which the gnap component is applied. Transaction handlers do not have any logic themselves to select different databases, so information about database and security context must be provided external to them.
The RetailMAX example store (a "database") makes some information publicly available. The URL stem for this store is /store/nz/example. Therefore, the gnap request url can be constructed as /store/nz/example/gnap/j/buck?.... This example will request a JSON formatted response, but other output encodings are permitted.
(Advanced, side issue) Technically, the /store/nz/example prefix is constructing a HOST transaction block, and binary request formats, such as direct TCP, can emulate this behaviour with the HOST transaction.
An integer is encoded as a sequence of digits, with an optional leading sign (+ or -). Leading zeros and plus sign (+) are optional and may be discarded. Large numbers are
On input, you can force the GNAP encoding to be 'E' (uppercase E) (4 byte signed integer type) by post fixing the field name with _E (eg "f123_E" or "f123:E")
On output dates are encoded as a pipe delimited list of fields, from year to second. for example, the 1st of March 2008 is delivered as "2008|3|1". For most languages this can be rapidly transformed into native date formats. Time is encoded in 24 hour time. Users are advised that the seconds field can range from 0 to 61 in rare circumstances. (leap seconds)
There are exceptions to this output format for some clients. These apply only to specified client types, such as iPhones being served dates from Meetu4.
On input the formats are slightly more flexible. You can encode in any of the following formats to most servers.
| Pattern | Example(s) | Description |
| YYYY|MM|DD|HH|mm|SS|CCC | 2008|03|01|13|52|05 | Preferred GDS date encoding |
| dd-mmm-yyyy hh:mm:ss.ccc | 1-Mar-2008 13:52:05 | Textual input format. The month must be encoded using 3 english letter format (jan, feb, etc) |
The format "dd/mm/yyyy" or "mm/dd/yyyy" is expressly forbidden. This format has two digit day and month fields and cannot distiguish between different users intentions. Is "3/1/2008" the 3rd of January, or the 1st of March? This depends on the user and the server cannot reliably interpret this value. Servers are free to report errors whenever this format is used.