Skip to content

Commit 002c4df

Browse files
nsheffnsheff
committed
add openapi yaml. Fix #92 
1 parent 03d0045 commit 002c4df

File tree

1 file changed

+232
-0
lines changed

1 file changed

+232
-0
lines changed

‎docs/pub/refget-openapi.yaml

+232
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
openapi: 3.0.0
2+
servers:
3+
- url: '/refget/1'
4+
info:
5+
description: >-
6+
System for retrieving sequence and metadata concerning a reference sequence
7+
object by hash identifiers
8+
version: '2.0.0'
9+
title: refget API
10+
contact:
11+
name: GA4GH Security Notifications
12+
email: [email protected]
13+
url: https://www.ga4gh.org/
14+
tags:
15+
- name: Metadata
16+
description: Services linked to retrieving metadata from an identifier
17+
- name: Sequence
18+
description: Services linked to fetching sequence from an identifier
19+
- name: Other
20+
description: Additional services
21+
paths:
22+
/sequence/service-info:
23+
get:
24+
summary: Retrieve a summary of features this API deployment supports
25+
operationId: serviceInfo
26+
tags:
27+
- Other
28+
responses:
29+
'200':
30+
description: Display of all known configurations for a service deployment
31+
content:
32+
application/json:
33+
schema:
34+
$ref: '#/components/schemas/RefgetServiceInfo'
35+
'415':
36+
$ref: '#/components/responses/BadFormat'
37+
'/sequence/{id}':
38+
get:
39+
summary: Get a sequence from a hash
40+
operationId: sequence
41+
description: |
42+
Retrieve a reference sequence using a hash function
43+
tags:
44+
- Sequence
45+
parameters:
46+
- in: path
47+
name: id
48+
description: The identifier to use. Should be a checksum hash identifier
49+
required: true
50+
schema:
51+
type: string
52+
default: 6681ac2f62509cfc220d78751b8dc524
53+
- in: query
54+
name: start
55+
description: Request a subsequence of the data (0-based)
56+
schema:
57+
type: integer
58+
format: int32
59+
minimum: 0
60+
- in: query
61+
name: end
62+
description: Request a subsequence of the data by specifying the end
63+
schema:
64+
type: integer
65+
format: int32
66+
minimum: 1
67+
- in: header
68+
name: Range
69+
required: false
70+
description: >-
71+
Specify a substring as a single HTTP Range.
72+
One byte range is permitted, and is 0-based inclusive.
73+
For example, 'Range: bytes=0-9' corresponds to '?start=0&end=10'.
74+
schema:
75+
type: string
76+
responses:
77+
'200':
78+
description: >-
79+
Successful retrieval of sequence. Returned as a single string with
80+
no line breaks
81+
content:
82+
text/plain:
83+
schema:
84+
type: string
85+
example: >-
86+
MSSPTPPGGQRTLQKRKQGSSQKVAASAPKKNTNSNNSILKIYSDEATGLRVDPLVVLFLAVGFIFSVVALHVISKVAGKLF
87+
'206':
88+
description: Successful retrieval of subsequence as a single string with no line breaks
89+
'302':
90+
description: Redirecting the client where the sequence can be retrieved
91+
'303':
92+
description: Redirecting the client where the sequence can be retrieved
93+
'307':
94+
description: Redirecting the client where the sequence can be retrieved
95+
'400':
96+
description: Invalid input; normally due to range parameter usage
97+
'404':
98+
description: Sequence was not found
99+
'415':
100+
$ref: '#/components/responses/BadFormat'
101+
'416':
102+
description: Invalid range request specified
103+
'501':
104+
description: The specified request is not supported by the server
105+
'/sequence/{id}/metadata':
106+
get:
107+
summary: Get reference metadata from a hash
108+
description: Retrieve a metadata about a reference sequence using a hash identifier
109+
operationId: metadata
110+
tags:
111+
- Metadata
112+
parameters:
113+
- in: path
114+
name: id
115+
required: true
116+
description: The identifier to use. Should be a checksum hash
117+
schema:
118+
type: string
119+
default: 6681ac2f62509cfc220d78751b8dc524
120+
responses:
121+
'200':
122+
description: Successful retrieval of sequence metadata
123+
content:
124+
application/json:
125+
schema:
126+
$ref: '#/components/schemas/Metadata'
127+
'404':
128+
description: Sequence hash was not found
129+
'415':
130+
$ref: '#/components/responses/BadFormat'
131+
components:
132+
responses:
133+
BadFormat:
134+
description: The requested data format is not supported by the endpoint
135+
NotFound:
136+
description: The requested resource was not found
137+
schemas:
138+
Metadata:
139+
type: object
140+
description: Holds information about a sequence checksum
141+
properties:
142+
metadata:
143+
type: object
144+
properties:
145+
id:
146+
type: string
147+
description: Query identifier. Normally the default checksum for a given service
148+
example: 6681ac2f62509cfc220d78751b8dc524
149+
md5:
150+
type: string
151+
description: MD5 checksum of the reference sequence
152+
example: 6681ac2f62509cfc220d78751b8dc524
153+
trunc512:
154+
type: string
155+
description: >-
156+
Truncated, to 48 characters, SHA-512 checksum of the reference
157+
sequence encoded as a HEX string. No longer a preferred serialisation of the SHA-512
158+
example: 959cb1883fc1ca9ae1394ceb475a356ead1ecceff5824ae7
159+
ga4gh:
160+
type: string
161+
description: >-
162+
A ga4gh identifier used to identify the sequence. This is a
163+
[base64url](defined in RFC4648 §5) representation of the 1st 24 bytes from a
164+
SHA-512 digest of normalised sequence. This is the preferred method of
165+
representing the SHA-512 sequence digest.
166+
example: ga4gh:SQ.aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2
167+
length:
168+
type: integer
169+
format: int64
170+
description: An decimal integer of the length of the reference sequence
171+
aliases:
172+
type: array
173+
items:
174+
$ref: '#/components/schemas/Alias'
175+
required:
176+
- id
177+
- length
178+
- md5
179+
- aliases
180+
Alias:
181+
type: object
182+
description: Allows the assignment of an identifier or alias to a naming authority
183+
properties:
184+
alias:
185+
type: string
186+
description: Free text alias for a given sequence
187+
example: chr1
188+
naming_authority:
189+
type: string
190+
description: 'Name of the authority, which issued the given alias'
191+
required:
192+
- alias
193+
- naming_authority
194+
RefgetServiceInfo:
195+
allOf:
196+
- '$ref': https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/service-info.yaml#/components/schemas/Service
197+
- type: object
198+
description: Extended capabilities of refget service-info response object
199+
required:
200+
- refget
201+
properties:
202+
refget:
203+
type: object
204+
required:
205+
- circular_supported
206+
- algorithms
207+
properties:
208+
circular_supported:
209+
type: boolean
210+
description: Indicates if the service supports circular location queries
211+
subsequence_limit:
212+
type: integer
213+
format: int64
214+
nullable: true
215+
description: Maximum length of sequence which may be requested using start and/or end query parameters
216+
algorithms:
217+
type: array
218+
items:
219+
type: string
220+
description: An array of strings listing the digest algorithms that are supported
221+
example:
222+
- md5
223+
- ga4gh
224+
identifier_types:
225+
type: array
226+
items:
227+
type: string
228+
description: An array of strings listing the type of name space that are supported
229+
example:
230+
- insdc
231+
- refseq
232+
- ensembl

0 commit comments

Comments
 (0)