Service Operation Guide

This section goes over how the service generally operates, and main ideas behind it.

In General

As stated, the External Item Search tool is a search aggregator from various sources. A single request to this service results in many calls to downstream source providers:

        flowchart TD
        start((Search Call))
        callsStart@{ shape: diamond, label: "Make External Calls" }
        call1[External Service Call 1]
        call2[External Service Call 2]
        call3@{ shape: procs, label: "..."}
        callsEnd@{ shape: diamond, label: "Ext Calls Return" }
        finish((Call Result))

        start --> callsStart
        callsStart --> call1
        callsStart --> call2
        callsStart --> call3

        call1 --> callsEnd
        call2 --> callsEnd
        call3 --> callsEnd

        callsEnd -- Streams results --> finish
    

Individual calls are made in a parallel fashion, and results are processed as such, and individual results are streamed back to the user as they come.

For example, calling /api/v1/search?lookupMethod=BARCODE&q=00888109010058 results in:

[
        {
                "service": "DATAKICK",
                "source": "DATAKICK",
                "method": "BARCODE",
                "name": "-  Blackberry peach",
                "unifiedName": "-  Blackberry peach",
                "description": "",
                "prices": {},
                "identifiers": {},
                "attributes": {
                        "gtin14": "00888109010058",
                        "size": "30ML",
                        "ingredients": "s"
                },
                "images": [],
                "links": {},
                "type": "SUCCESS"
        }
]

It should be noted that individual calls to external services are cached, in order to prevent the waste of usage-based limits.

Terminology

Service / Provider

The terms “service” and “provider” are used here interchangeably. A service / provider is an upstream source of item data.

Source

A “source” is mostly 1:1 with a “service”. The reason this distinction exists is that sometimes some services themselves are aggregators. This is used to be able to specify searching (or not searching) for sources behind these aggregators.

Lookup Method

There are a few general types of data that items are identified by. The lookup method is our way to distinguish and search by these.

Example, TEXT is for a clear text search. BARCODE is searching for any standard barcode (UPC, ISBN, etc).