Skip to content

Commit

Permalink
[dataquery] Define new swagger schema for data query API
Browse files Browse the repository at this point in the history
This defines the schema I've been using to design a QueryEngine
(rather than CouchDB) based data query tool.
  • Loading branch information
driusan committed Dec 13, 2022
1 parent fa666f5 commit cb186bd
Showing 1 changed file with 331 additions and 0 deletions.
331 changes: 331 additions & 0 deletions modules/dataquery/static/schema.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,331 @@
openapi: 3.0.1
info:
title: LORIS Data Query Tool API endpoints
description: |-
This is the API for the parts of the Loris data query module which are intended to be used as an API.
contact:
name: LORIS Development Team
url: 'https://github.com/aces/Loris'
license:
name: 'GNU Public License, Version 3'
url: 'https://opensource.org/licenses/GPL-3.0'
version: "3.0"
servers:
- url: /dataquery/
security:
- ApiKeyAuth: []
paths:
/queries:
get:
summary: Get a list of a recent, shared, and study (top) queries to display.
responses:
'200':
description: Successfully operation
content:
application/json:
schema:
$ref: '#/components/schemas/AllQueries'
'403':
description: Permission denied
post:
description: Create a new query and return the QueryID. If the same query (fields and criteria) already exists, the same QueryID will be returned instead of a new one being created.
requestBody:
description: A Query object (without the QueryID)
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
responses:
'200':
description: Query successfully created
content:
application/json:
schema:
type: object
properties:
QueryID:
type: integer
'400':
description: An invalid body was supplied
content:
application/json:
schema:
type: object
properties:
error:
type: string
/queries/{QueryID}:
parameters:
- name: QueryID
in: path
description: the QueryID returned by posting to /queries
required: true
style: simple
schema:
type: integer
get:
responses:
'200':
description: The Query was successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
'403':
description: Permission denied
patch:
parameters:
- name: share
in: query
style: spaceDelimited
schema:
type: boolean

- name: unshare
in: query
style: spaceDelimited
schema:
type: boolean
- name: star
in: query
style: spaceDelimited
schema:
type: boolean
- name: unstar
in: query
style: spaceDelimited
schema:
type: boolean
- name: type
in: query
style: spaceDelimited
schema:
type: string
enum: ['top', 'untop', 'dashboard']
- name: name
in: query
style: pipeDelimited
schema:
type: string
responses:
'400':
description: Bad request. Most likely caused by one or more incompatible patches to be done at the same time.
/queries/{QueryID}/run:
parameters:
- name: QueryID
in: path
description: the QueryID returned by posting to /queries
required: true
style: simple
schema:
type: integer
get:
description: |-
Run the query QueryID and returns the results.
This endpoint will result in a new query run being generated, which will be returned in the 'recent' queries of the user on the /queries endpoint.
responses:
'200':
description: The query was able to be successfully run
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/QueryResults'
'500':
description: Something went wrong on the server running the query
/queries/{QueryID}/count:
parameters:
- name: QueryID
in: path
description: the QueryID returned by posting to /queries
required: true
style: simple
schema:
type: integer
get:
responses:
'200':
description: |-
A count of the number of candidate matches that would be returned if the query were to be run by the current user right now.
This endpoint does *not* result in a new query run being generated or run the query, it only returns the count of how many candidates would match if the query *were* to be run.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: The number of candidates that match the filters
example: 34
/queries/{QueryID}/run/{QueryRunID}:
description: |-
Returns the cached results of a previously run query
Note: This endpoint is aspirational.
parameters:
- name: QueryID
in: path
description: the QueryID returned by posting to /queries
required: true
style: simple
schema:
type: integer
- name: QueryRunID
in: path
description: the identifier of a previous run for this QueryID.
required: true
style: simple
schema:
type: integer
get:
responses:
'500':
description: Not implemented
content:
application/json:
schema:
type: object

components:
schemas:
AllQueries:
type: object
properties:
recent:
type: array
items:
$ref: '#/components/schemas/QueryRun'
shared:
type: array
items:
$ref: '#/components/schemas/Query'
topqueries:
type: array
items:
$ref: '#/components/schemas/Query'

Query:
type: object
properties:
type:
type: string
enum: ['candidates']
example: "candidates"
Name:
type: string
example: "My Query"
SharedBy:
type: array
items:
type: string
example: "admin"
Starred:
type: boolean
Shared:
type: boolean
QueryID:
type: integer
example: 3
fields:
type: array
items:
$ref: '#/components/schemas/QueryField'
criteria:
$ref: '#/components/schemas/QueryCriteriaGroup'
required:
- type
- fields
QueryRun:
type: object
properties:
RunTime:
type: string
example: "2022-11-02 15:34:38"
Query:
$ref: '#/components/schemas/Query'
QueryField:
type: object
properties:
module:
type: string
example: "candidate_parameters"
category:
type: string
example: "Identifiers"
field:
type: string
example: "CandID"
required:
- module
- category
- field
QueryCriteriaGroup:
type: object
description: An and/or group used for filtering, all items in the group must be the same operator (but an item in the group may be a query criteria subgroup using a different operator)
properties:
operator:
type: string
enum: ['and', 'or']
description: The operator to connect the items in group
group:
type: array
items:
$ref: '#/components/schemas/QueryGroupField'
QueryGroupField:
type: object
properties:
module:
type: string
example: "candidate_parameters"
category:
type: string
example: "Identifiers"
fieldname:
type: string
example: "CandID"
op:
type: string
enum:
# Standard operators
- 'lt'
- 'lte'
- 'eq'
- 'neq'
- 'gte'
- 'gt'
# Enum operator
- 'in'
# String operators
- 'startsWith'
- 'endsWith'
- 'contains'
# Optional cardinality operators
- 'isnotnull'
- 'isnull'
# Many cardinality operators
- 'exists'
- 'notexists'
- 'numberof'
value:
type: string
required:
- module
- category
- fieldname
- op
- value
QueryResults:
description: |-
The result of running a query.
The result is a stream of data for each CandID that matched by the query. Candidates are separated by an ASCII record separator (0x??). Each cell within the candidate is separated by an ASCII ?? separateor (0x??). Each row should have the exact number of fields that were in the query fields attribute.
Within each cell, the format of the data varies based on the dictionary of the field type. If the data is candidate scoped, a value is directly returned. If it is session scoped variable or has cardinality of many:one, a JSON object is returned.
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Authorization
in: header

0 comments on commit cb186bd

Please # to comment.