eLink requests are made using a standard URL path, with fixed methods, or predicates, of selecting data subsets.
There are two main types of calls:
- Reading of information, which uses the url form /gnap/BUCK?3=name
- Editing and inserting, with the url form /gnap/DATI?8=name
To call the API endpoint "retailmax.elink.products" which is used to list products in the system create the URL of the form
http://your-server/gnap/buck?3=retailmax.elink.products
The server will return a standard response, which by default is relatively cryptic, but quite efficient for the server to process.
<ARAY>
<DATS>
<f100>123</f100>
<f101>Product Number 1</f101>
</DATS>
<DATS>
<f100>456</f100>
<f101>Super Tasty Snacks</f101>
</DATS>
...
</ARAY>
Rule 1: Internally, fields and attributes are represented using numbers, typically 100+, to represent data. Numbers are very easy and efficient for computer/computer use and space efficient for large volumes. If you want a specific output format, you need to ask for it.
Output Formats
Internally, the server processes eLink requests using binary format. The response to your call is then converted to different formats before final delivery to you. A range of different output formats is available as which is the best format depends on what tools you are using, your required latency and processing needs as well as volume and type of data being requested.
For text based response formats (XML, JSON, Text) you select either the named or numeric response format.
Requesting Numeric XML response format
This is the default, so simply generate the call
http://your-server/gnap/buck?3=retailmax.elink.productsResponse
<ARAY>
<DATS>
<f100>123</f100>
<f101>Product Number 1</f101>
</DATS>
...
</ARAY>
Requesting Named XML response format
Named XML has standardised names for tags rather than numeric format. Not all APIs return named fields yet, contact Fieldpine if you wish to use named format for an API that does not return names. Some high volume and infrequently used APIs may not return named format due to space and processing speed issues.
http://your-server/gnap/M/buck?3=retailmax.elink.productsResponse
<ARAY>
<DATS>
<Pid>123</Pid>
<Description>Product Number 1</Description>
</DATS>
...
</ARAY>
Requesting Named JSON response format
Named JSON has standardised names for tags rather than numeric format and is a very popular response format.
http://your-server/gnap/J/buck?3=retailmax.elink.productsResponse
"RootType": "ARAY",
[
{ "Pid": 123, "Description": "Product Number 1" },
{ "Pid": 456, "Description": "Super Tasty Snacks" }
]
Requesting Numeric JSON response format
Numeric JSON returns the internal number based names for tags.
http://your-server/gnap/j/buck?3=retailmax.elink.productsResponse
"RootType": "ARAY",
[
{ "f100": 123, "f101": "Product Number 1" },
{ "f100": 456, "f101": "Super Tasty Snacks" }
]
Requesting Named Text response format
Named Text has standardised names for tags rather than numeric format. This format uses a fixed line structure with CR line delimiter.
http://your-server/gnap/T/buck?3=retailmax.elink.productsResponse
ARAY +DATS Pid=123 Description=Product Number 1 -DATS +DATS Pid=456 Description=Super Tasty Snacks -DATS
Requesting Numeric Text response format
Numeric Text returns the numeric field name at the beginning of the line This format uses a fixed line structure with CR line delimiter.
http://your-server/gnap/t/buck?3=retailmax.elink.productsResponse
ARAY +DATS 100=123 101=Product Number 1 -DATS +DATS 100=456 101=Super Tasty Snacks -DATS
Requesting Excel Spreadsheet response format
Most API responses can be converted to Excel spreadsheets automatically
http://your-server/gnap/o/[xl,100,Products.xlsx]/buck?3=retailmax.elink.productsResponse
If issued interactively, the browser will either prompt to save file, or display spreadsheeet, depending on client browser configuration. The filename should default to Products.xlsx
As normal, the default response type is numeric, but the following format can be used to request column headings have names where possible
http://your-server/gnap/o/[xl,100,AllStores.xlsx,120=3]/buck?3=retailmax.elink.locations
Requesting JSON-P response format
Requesting JSON-P (2) response format
Requesting PDF response format
Requesting HTML response format
Requesting Binary response format
When you call eLink via HTTP, the response is automatically defaulted to Numeric XML. If you want to force binary format, use the /b option.
http://your-server/gnap/b/buck?3=retailmax.elink.products
The response will be an octet-stream with the data in binary format.
Transactions
HTTP GET transactions are used for reading from "Buckets" and POST transactions may also be used for reading buckets with large volumes of input data or parameters. POST transactions are required for write transactions.
A "Bucket" is the eLink term for the collection of information returned, as in "give me a bucket of product records". Buckets are similar in concept to SQL Views, they are often derived from multiple underlying data sources and represent logical objects rather than the physical database storage representation. In SQL to retrieve product details, current stock levels and on-order status, you may create a join of multiple tables, or issue several different queries. With eLink buckets you request a single bucket for the products you are interested in, and indicate in your request the extra information (stock levels, order status) you require. The bucket itself will retrieve and return the extended information.
As buckets can fetch many many additional pieces of information, there is no real equivalent of SQL "select *", although you can approximate this if you really want to. Indicating what information you wish to be returned is done through a "want list" argument, which is a standardised way of expressing the fields you require. All buckets will return a default set of attributes if you do not specify what information you want to be returned.