Skip to content

Latest commit

 

History

History
307 lines (285 loc) · 14.6 KB

api.org

File metadata and controls

307 lines (285 loc) · 14.6 KB

/api/1/

standard query parameters

Multiple arguments may be provided for those fields with arity n in the table below. If multiple values are provided then the api will return records that match any one of the provided values (that is union, or or behavior).

If a parameter is passed to an endpoint that is unknown or not accepted by that endpoint a response with a 422 status code listing the bad parameter(s) will be returned.

For example if a query string with the form ?dataset=uuid&aspect=distance&aspect=time will translate into sql as something like WHERE i.dataset = uuid AND a.label = ANY('{"distance", "time"}').

Most of these query parameters operate as WHERE clauses that are all matched against quantitative or categorical values, that is they are connected by AND (unlike multiple arguments).

By default categorical and quantitative values are connected by an INTERSECT, however for some queries, e.g. ones that provide and ?object argument, this means that the results set will always be empty except in cases where a single object provided both cat and quant values. You can pass ?union-cat-quant=true to change the behavior to UNION. The default behavior for this may change per endpoint in which case we will document which endpoints default to UNION.

All arguments that are provided must satisfy on at least one single quantitative or categorical value, so e.g. ?aspect=a&value-quant-min=1 selects for values with aspect a that are greater than or equal to 1. When providing multiple aspects this means that the range restriction will apply to values from any of those aspects which can be a bit confusing if they are distance and time but less confusing if they are e.g. distance-metric-m-version-1 and distance-metric-m-version-2.

The values provided as arguments for desc-inst and aspect are resolved to match all subclasses, so if distance is provided results will match values with aspects distance-metric-m-version-1 and distance-metric-m-version-2 along with other subclasses of distance.

Behavior or desc/*, terms, units, and aspects endpoints is currently limited to only querying values of the same type, so e.g. it is not possible to limit the results of a query to the aspects endpoint by passing ?value-cat=some-cat-value and it is not possible to limit the results of a query to the terms endpoint by passing ?aspect=some-aspect. This will be fixed eventually.

  • prov only accepted on values/* endpoints
  • source-only only accepted on the objects endpoint
  • value-cat* and desc-cat not accepted on values/quant
  • value-quant*, unit, aspect, and agg-type not accepted on values/cat
  • desc-* are not accepted on desc/*
  • value-cat is not accepted on terms
  • unit is not accepted on units
  • aspect is not accepted on aspects
nametypearity
objectuuidn
updated-transitivetimestamp1
desc-inststringn
datasetuuid1
inststringn
inst-parentstringn
subjectstringn
samplestringn
include-equivalentbool1
desc-catstringn
value-catstringn
value-cat-openstringn
unitstringn
aspectstringn
agg-typestring1
value-quantnumeric1
value-quant-marginnumeric1
value-quant-minnumeric1
value-quant-maxnumeric1
limitinteger1
union-cat-quantbool1
source-onlybool1
include-unusedbool1
provbool1

Invalid combinations are marked with an x. Non-meaningful combinations are marked with a q. Not-implemented are marked with ni.

arg V endpoint >objectsvalues/instvalues/catvalues/quantdesc/instdesc/catdesc/quanttermsunitsaspects
object
updated-transitive
desc-instx
dataset
inst
inst-parent
subject
sample
include-equivalentnininininininininini
desc-catxxqqq
value-catxqxqq
value-cat-openxqqq
unitxqqx
aspectxqqx
agg-typexqq
value-quantxqq
value-quant-marginxqq
value-quant-minxqq
value-quant-maxxqq
limitnininininininininini
union-cat-quant
source-onlyxxxxxxxxx
include-unusedxxxx
provxxxxxxx

response

If everything proceeds as expected then you will receive an HTTP response with a 200 status code containing json structured as show below.

  • endpoint is the normalized endpoint name
  • parameters are the interpretation of the url query string parameters passed
  • records is the number of results
  • result is the list of objects returned by the query
{
    "type": "quantdb-query-result",
    "endpoint": "some/endpoint",
    "parameters": {"include-unused": true},
    "records": 1,
    "result": [ {"type": ...} ... ]
}

If a query parameter is passed that is not valid for an the endpoint then you will receive a 422 response.

{"error": ["unknown-parameter-name-that-was-passed"], "http_response_status": 422}

All other errors return a standard abort that is not json.

endpoints

objects

  • query data objects associated with instances matching parameters
  • accepts standard query parameters

/values/inst or instances

  • query instances matching parameters
  • accepts standard query parameters

use cases

show me all measurements that have been made on a subject or part of that subject or sample derived from that subject

for this just stick it in instances

values or values/cat-quant

  • query categorical and quantitative values matching parameters
  • accepts standard query parameters

values/cat

  • query categorical values matching parameters
  • accepts standard query parameters (but will ignore those for quantitative values)

values/quant

  • query quantitative values matching parameters
  • accepts standard query parameters (but will ignore those for categorical values)

desc/inst or descriptors/inst or classes

  • list instance descriptors (aka classes) matching parameters
  • accepts standard query parameters (see notes on limitations above)

desc/cat or descriptors/cat or predicates

  • list categorical descriptors (aka predicates or properties) matching parameters
  • accepts standard query parameters (see notes on limitations above)

desc/quant or desciptors/quant

  • list quantitative descriptors matching parameters
  • accepts standard query parameters (see notes on limitations above)

terms or controlled-terms

  • list terms matching parameters
  • accepts standard query parameters (see notes on limitations above)

units

  • list units matching parameters
  • accepts standard query parameters (see notes on limitations above)

aspects

  • list aspects matching parameters
  • accepts standard query parameters (see notes on limitations above)