O3 DataRead

The O3 DataRead interface allows rapid access to small slices of data for lookup and translation purposes. It can be considered a form of lightweight GraphQL in terms of operation, although it has no connection to that at all. The O3 DataRead allows you to quickly fetch these sorts of things

• Get a list of products and their sizes ( /o3/dataread/products/pid/size )
• Get a list of customers and their city ( /o3/dataread/customers/cid/city )
• Get a list of supplier IDs and names ( /o3/dataread/suppliers/spid/name )
• Get a list of products and their supplier names ( /o3/dataread/products/pid/supplier.name )

This interface is not a replacement for REST style APIs which allow you to retrieve a large number of columns for a varying number of rows. REST APIs are suitable for "get all details for all sales yesterday".

• This interface only replies in JSON.
• Output may be restricted by security controls. User A might see more/less results than user B
• Not all underlying data is available. You cannot bulk download passwords for example

Syntax

The URL is /o3/dataread/TABLE/KEY-FIELD/WANT-FIELD where:

• "TABLE" is a concept, not always a direct database table, although typically they are database tables.
• "TABLE" may be a logical concept. For examples "locations" as a table name means the list of the stores, but excludes closed stores
• KEY-FIELD is a physical field on the table
• WANT-FIELD is either
  1. A physical field on the table
  2. A defined dereference table

Dereferenced Fields

The want-field names for a table are able to extend to related information, essentially a dereference. For example, the query /o3/dataread/products/pid/department.name returns the associated department name for each PID

Security

Generic "let me at the underlying data" can often expose too much information.

1. The /O3 url is designed for easy firewall release. This was a primary factor in the URL design

Calling From Javascript

    var sPidPlu = {}
    fetch("/o3/dataread/products/pid/plucode").then(function (rsp) { return rsp.json() })
		.then(function (d) {
			sPidPlu = d.v;
        })

    // Once data has been retrieved, then to retrive a PLU/SKU for a given Pid...
    let SKU = sPidPlu[Pid];

Output Formats

O3 DataRead is opinionated about output formats. The values you request are always in the "v" field. "v" can be an object or array depending on the query.

If the query is /o3/dataread/table/UNIQUE-KEY/Wanted-Field where UNIQUE-KEY is a field that is guaranteed to be unique per row, then the output is

{
    "v": {
        "key1": "Wanted-Field-Value-1",
        "key2": "Wanted-Field-Value-2",
        ...
        "keyNNN": "Wanted-Field-Value-NNN"
    },
    "control": {
        ...
    }
}

If the query is /o3/dataread/table/NON-UNIQUE-KEY/Wanted-Field where NON-UNIQUE-KEY is any field that is not known to be guaranteed unique per row, then the output is

{
    "v": {
        "key1": [ "Wanted-Field-Value-1", "Wanted-Field-Value-2"],
        "key2": [ "Wanted-Field-Value-3"],
        ...
        "keyNNN": [ "Wanted-Field-Value-NNN", ... "Wanted-Field-Value-ZZZ"]
    },
    "control": {
        ...
    }
}

Output Examples

Consider a table "cats" containing this information

ID (Primary Key)	Size	Age	Name
1	Large	18	Robyn
2	Small	43	Robyn
3	Small	18	Anita
4	Lge	5	Sue
5		18	Bob

The Query /o3/dataread/cats/id/name returns values in a Key/Value object, as "id" is guaranteed unique.

{
    "v" {
        "1": "Robyn",
        "2": "Robyn",
        "3": "Anita",
        "4": "Sue",
        "5": "Bob"
    }
}

While the Query /o3/dataread/cats/name/id returns values in a Key/Value object, but with results in arrays

{
    "v" {
        "Robyn": [1,2],
        "Anita": [3],
        "Sue": [4],
        "Bob": [5]
    }
}

You can request any field as the "key" /o3/dataread/cats/age/name returns the names of cats at each age step.

{
    "v" {
        "18": ["Robyn", "Anita", "Bob"],
        "43": ["Robyn"],
        "5": ["Sue"]
    }
}