-
Notifications
You must be signed in to change notification settings - Fork 5
/
individuals_api.yml
388 lines (388 loc) · 12.8 KB
/
individuals_api.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
openapi: 3.0.1
info:
title: Virtual platform Beacon API
x-beaconVersion: v2.0
description: EJPRD virtual platform data record APIs
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: v1.0
servers:
- url: https://rdnexusdev.molgeniscloud.org/cv2/BeaconAPI/
description: Development server
paths:
/info:
get:
summary: "Get information regarding this beacon."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/InfoResponse'
/filtering_terms:
get:
summary: "Get the valid filtering terms to be used in querying/handled by this beacon."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/FilterTermsResponse'
/map:
get:
summary: "Get the list of endpoints included in this beacon i.e., individuals."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/MapResponse'
/service-info:
get:
summary: "Get information about the beacon using GA4GH ServiceInfo format."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/ServiceInfoResponse'
/configuration:
get:
summary: "Get the configuration of this beacon."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/ConfigurationResponse'
/entry_types:
get:
summary: "Get the list of beacon entry types."
tags:
- Informational Endpoint
responses:
200:
$ref: '#/components/schemas/EntryTypesResponse'
/individuals:
post:
summary: "Request to retrive count of individuals from a data source (i.e. patients)"
tags:
- Query Endpoint
operationId: individuals_request
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IndividualRequest'
required: true
responses:
200:
$ref: '#/components/schemas/IndividualResponse'
400:
description: "Input data malformed"
content: {}
403:
description: "The data source does not allow this API call"
content: {}
security:
- apiAuth: []
components:
schemas:
IndividualRequest:
required:
- meta
- query
type: object
properties:
meta:
$ref: '#/components/schemas/MetaContent'
query:
$ref: '#/components/schemas/RequestQuery'
description: "Request to return individuals count for given CDEs input parameters"
# RequestProperties:
# type: object
# properties:
# meta:
# $ref: '#/components/schemas/MetaContent'
# query:
# $ref: '#/components/schemas/RequestQuery'
RequestQuery:
type: object
properties:
filters:
$ref: '#/components/schemas/RequestFilter'
description: "Input of the query"
RequestFilter:
required:
- type
- id
- operator
type: array
items:
type: object
properties:
type:
type: string
# enum: [obo:NCIT_C28421, sio:SIO_001003, sio:SIO_010056, obo:NCIT_C16612, obo:NCIT_C25150, efo:EFO_0004847, obo:NCIT_C156420]
description: >
Concept ID of CDEs.
Allowed terms:
* `obo:NCIT_C28421` - Sex
* `sio:SIO_001003` - Diagnosis of the rare disease
* `sio:SIO_010056` - Phenotype
* `obo:NCIT_C16612` - Causative Gene(s)
* `obo:NCIT_C25150` - Age this year
* `efo:EFO_0004847` - Age at disease manifestation
* `obo:NCIT_C156420` - Age at diagnosis
# description: "Concept ID of CDEs. e.g sex(obo:NCIT_C28421)"
example: "obo:NCIT_C28421"
id:
type: string
description: >
The actual values of the CDE. Allowed values:
* For `obo:NCIT_C28421`(Sex):
* `obo:NCIT_C16576`, (Female)
* `obo:NCIT_C20197`, (Male)
* `obo:NCIT_C124294`, (Undetermined)
* `obo:NCIT_C17998` (Unknown)
* For `sio:SIO_001003`(Diagnosis) - Any ORPHA term
* For `sio:SIO_010056`(Phenotype) - Any HPO term
* For `obo:NCIT_C16612`(Causative Gene) - Any HGNC Gene symbol
* For `obo:NCIT_C25150`(Age this year) - Any integer
* For `efo:EFO_0004847`(Age at disease manifestation) - Any integer
* For `obo:NCIT_C156420`(Age at diagnosis) - Any integer
enum: [obo:NCIT_C16576,obo:NCIT_C20197,obo:NCIT_C124294,obo:NCIT_C17998, An Orphanet Term, A HPO Term, An integer for age ranges]
example: "obo:NCIT_C16576"
operator:
type: string
description: "This is a advance filter option to include comparison operators in the query."
example: "="
description: "Query parameters to filter individuals based on CDEs."
InfoResponse:
required:
- meta
- response
type: object
properties:
meta:
$ref: '#/components/schemas/MetaContent'
response:
$ref: '#/components/schemas/InfoResponseContent'
description: |
Respond with information regarding this Beacon.
FilterTermsResponse:
description: |
List of filtering terms for querying this Beacon.
ServiceInfoResponse:
description: |
Respond with the Service Info of this Beacon.
MapResponse:
description: |
Respond with the list of available query endpoints in this Beacon.
EntryTypesResponse:
required:
- meta
- response
type: object
properties:
meta:
$ref: '#/components/schemas/MetaContent'
response:
$ref: '#/components/schemas/ETResponseContent'
description: |
Respond with the entry types available in this Beacon Implementation.
ConfigurationResponse:
description: |
Respond with this Beacon's configuration information.
MetaContent:
description: |
Information about the response that could be relevant for the Beacon client in order to interpret the results.
required:
- apiVersion
- beaconId
- returnedSchemas
type: object
properties:
apiVersion:
type: string
description: |
Version of the API.
example: v2.0
beaconId:
type: string
description: |
Identifier of the beacon, as defined in Beacon, in reverse domain name notation.
example: BeaconAPI.cv2.rdnexusdev.molgeniscloud.org
returnedSchemas:
type: object
description: |
Set of schemas to be used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
InfoResponseContent:
description: |
Metadata describing a Beacon instance.
required:
- apiVersion
- environment
- id
- name
- organisation
properties:
apiVersion:
type: string
description: |
Version of the API provided by the Beacon.
example: v2.0
environment:
type: string
description: |
Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Allowed: prod, test, dev, staging
example: dev
id:
type: string
description: |
Unique identifier of the Beacon. Use reverse domain name notation.
name:
type: string
description: |
Name of the Beacon.
organisation:
type: object
description: |
Organization owning the Beacon.
required:
- id
- name
properties:
id:
type: string
description: |
Unique identifier of the organization.
name:
type: string
description: |
Name of the organization.
ETResponseContent:
required:
- entryTypes
type: object
properties:
entryTypes:
required:
- Individuals
type: object
description: |
List of entry types.
properties:
Individuals:
description: |
Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to describe each type of entities included in this beacon, hence Beacon clients could have some metadata about such entities.
required:
- defaultSchema
- id
- name
- ontologyTermForThisType
- partOfSpecification
type: object
properties:
defaultSchema:
description: |
Definition of an annotated URL address or a file reference.
required:
- id
- name
- referenceToSchemaDefinition
properties:
id:
type: string
description: |
A (unique) identifier of the element.
example: Individuals
name:
type: string
description: |
A distinctive name for the element.
example: Individuals
referenceToSchemaDefinition:
type: string
description: |
Conforming Schema of the element.
example: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2-Models/main/BEACON-V2-draft4-Model/individuals/defaultSchema.json
id:
description: |
A unique identifier of the element.
type: string
example: Individuals
name:
description: |
A distinctive name for the element.
type: string
example: Individuals
ontologyTermForThisType:
description: |
Definition of an ontology term.
type: object
required:
- id
properties:
id:
description: |
A CURIE identifier as `id` for ontology term.
example: NCIT:C25190
type: string
partOfSpecification:
description: |
This label is to group together entry types that are part of the same specification.
type: string
example: Beacon v2.0
description: |
Respond with a list of entry types conforming to Beacon v2 spec.
IndividualResponse:
description: |
Response of a query over individuals counts.
required:
- meta
- responseSummary
type: object
properties:
meta:
$ref: '#/components/schemas/MetaContent'
responseSummary:
$ref: '#/components/schemas/IndividualResponseContent'
info:
description: |
Beacon only responds with this info object if there are any unsupported filters in the query.
$ref: '#/components/schemas/WarningResponse'
WarningResponse:
description: |
Any unsupported filters go here.
required:
- warnings
properties:
warnings:
type: object
description: |
Respond with a list of unsupported filter(s).
example: obo:NCIT_C16612
IndividualResponseContent:
required:
- exists
- numTotalResults
type: object
properties:
exists:
type: boolean
description: |
Indicator of whether any individual was observed in the
data source for the given query with CDEs parameter. This should be non-null, unless there was an error, in which case `error` has to be non-null.
numTotalResults:
type: integer
description: |
Response of the query indicating if the query yield any results. If the query is successful then the count will be returned as a response.
securitySchemes:
apiAuth:
type: apiKey
in: header
name: auth-key