Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom

[dataquery] Define new swagger schema for data query API #8219

Merged
merged 6 commits into from
Dec 19, 2022
Merged

[dataquery] Define new swagger schema for data query API #8219

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cb186bd
[dataquery] Define new swagger schema for data query API
driusan Nov 7, 2022
4f6401a
Update schema after Xaviers review
driusan Dec 16, 2022
bdda21b
Create QueryObject
driusan Dec 16, 2022
b742752
Change to POST, add QueryRunID to query run
driusan Dec 16, 2022
911bd8c
Split queries and queryruns into two different endpoints
driusan Dec 19, 2022
ec75e95
Add QueryURI to QueryRun
driusan Dec 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
353 changes: 353 additions & 0 deletions modules/dataquery/static/schema.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,353 @@
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/
driusan marked this conversation as resolved.
Show resolved Hide resolved
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:
xlecours marked this conversation as resolved.
Show resolved Hide resolved
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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think post would make more sense. This is creating a queryRun so I don't think it is safe (as in rfc2616 safe)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

returning 201 Created with location header set to /queries/{QueryID}/run/{QueryRunID} would be good as well.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how do you denote "Location header" in swagger?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually that can't be done right now because that end point is not implemented so it would mean it's impossible to get results. Once it is implemented, the schema could be updated.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

    '201':
      description: The visit was created successfully
      headers:
        Content-Location:
          description: The URL of the new visit.
          style: simple
          explode: false
          schema:
            type: string

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 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:
driusan marked this conversation as resolved.
Show resolved Hide resolved
type: object
properties:
recent:
type: array
items:
$ref: '#/components/schemas/QueryRun'
queries:
type: array
items:
$ref: '#/components/schemas/Query'
Query:
type: object
properties:
xlecours marked this conversation as resolved.
Show resolved Hide resolved
self:
type: string
description: |-
A URL that this query can be accessed at.

Accessing the query directly through the URL is sure to have the same fields
and criteria, but other details of the object returned may not be identical.

For instance, the starred and name properties may vary based on the user
accessing the URI.
example: "https://example.com/dataquery/queries/4"
type:
type: string
enum: ['candidates']
example: "candidates"
AdminName:
type: string
descripton: The name given by the admin for a pinned query
example: "Important Study Query Of Missing T1s"
Name:
type: string
description: The name given by the current user for this query
example: "My Query"
SharedBy:
type: array
items:
type: string
example: "admin"
Starred:
type: boolean
description: The query has been starred by the user
Public:
type: boolean
description: The query has been shared (made public to all users)
Pinned:
type: boolean
description: The query has been pinned by an administrator
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:
self:
type: string
description: A URL to access this query run
example: "https://example.com/dataquery/queries/3/run/34"
RunTime:
xlecours marked this conversation as resolved.
Show resolved Hide resolved
type: string
example: "2022-11-02 15:34:38"
QueryID:
type: integer
description: A reference to an object in the queries property identified by QueryID
example: 3
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