-
Notifications
You must be signed in to change notification settings - Fork 5
/
openapi.yml
535 lines (528 loc) · 18.8 KB
/
openapi.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
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
openapi: '3.0.2'
info:
title: ediarum.WEB API 1.0
description: This is the documentation of the ediarum.WEB API.
version: '1.0.0'
servers:
- url: /api
tags:
- name: object
description: Information about single object
- name: object group
description: Endpoint to all object of a type
- name: search
description: Endpoint to search specified indexes
paths:
/api/{object-type}:
get:
tags:
- object group
- search
summary: List of objects or relations
description: |
Returns a list of all items of an object type or relation type as JSON.
*Attention: Because of performance issues only 10'000 entries are returned.
If more are requested please use the `limit` parameter.*
Examples:
- manuscript list filtered by repository: `/api/ms?show=list&city=Berlin&repository=Staatsbibliothek`
- first twenty entries of persons: `/api/persons?show=list&order=label&range=20&page=1`
- show letters from berlin containing the word 'Wetter': `/api/letters?show=list&place=Berlin&search=Wetter`
parameters:
- name: object-type
in: path
description: ID of the object type
required: true
schema:
type: string
- name: \{variable\}
in: query
description: For defined properties GET-parameter can be added. E.g. if `city` is a defined property it is possible to filter the list by adding `city=Berlin`.
schema:
type: string
- name: from
in: query
description: Defines which is the first item to be shown. To be used with `range`.
schema:
type: integer
- name: limit
in: query
description: Optional parameter. Defines how many (unordered) object entries are retrieved.
schema:
type: integer
default: 10000
- name: order
in: query
description: By which the list should be ordered
schema:
type: string # TODO there are some values
- name: page
in: query
description: Defines which page of list results should be returned. To be used with `range`.
schema:
type: integer
- name: range
in: query
description: How many items should be return. To be used with `page` or `from`.
schema:
type: integer
- name: search
in: query
description: Filters the objects by a search. Can be combined with other filters. To be used with `show=(all, compact, list)`.
schema:
type: string
- name: search-type
in: query
description: To be used with `search`. If not set, the exact matches are found. Multiple words are separated with a space.
schema:
type: string
enum:
- regex # for one or more words (separated by space) using regular expressions
- phrase # for a query of multiple words. With `slop` the distance can be defined (default is 1).
- lucene # for a lucene query, see <https://lucene.apache.org/core/2_9_4/queryparsersyntax.html>
- name: show
in: query
description: What should be retrieved
schema:
type: string
enum:
- all # show all objects
- compact # show all objects but in compact form, i.e. without properties
- filter # show the filter definitions
- list # show objects matching the filter criteria
- name: slop
in: query
description: The distance of words in a phrase search. To be used with `search` and `search-type=phrase`.
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectGroup'
/api/{object-type}/{object-id}:
get:
tags:
- object
- search
summary: Get object
description: |
Returns a information of a single object.
Examples:
- XML representation: `/api/persons/p123456?output=xml`
- XML output with special view: `/api/letters/l123456?output=xml&view=my_view`
- JSON information of a person: `/api/person/p123456`
- JSON list of retrievable chapters: `/api/texts/m41?part=chapter`
- XML output of chapter 1: `/api/texts/m41/1`
parameters:
- name: object-type
in: path
description: ID of the object type
required: true
schema:
type: string
- name: object-id
in: path
description: ID of the object
required: true
schema:
type: string
- name: output
in: query
description: Defines which object representation is shown. If not set some object information is retrieved as JSON.
schema:
type: string
enum:
- xml # the XML representation of the object is retrieved. Can be used with `view`.
- html # a HTML serialization of the object is retrieved. To be used with `view`.
- text # a text serialization of the object is retrieved. To be used with `view`.
- json-xml # some of the object information is retrieved as JSON, including the XML.
- name: view
in: query
description: defines which view (see [APPCONF.md](APPCONF.md)) is used to transform the object. The result is retrieved. To be used with `output`.
schema:
type: string
- $ref: '#/components/parameters/searchParam'
- $ref: '#/components/parameters/searchTypeParam'
- $ref: '#/components/parameters/searchXpathParam'
- $ref: '#/components/parameters/slopParam'
- $ref: '#/components/parameters/kwicWidthParam'
- name: part
in: query
description: If set the IDs of found passages of this definition are shown.
schema:
type: string
example: book-chapter
- name: part-def
in: query
description: To be used with `search`. Specifies to show to which parts the hits belong to.
schema:
type: string
example: book-chapter-segment
responses:
'200':
description: OK
content:
application/xml:
schema:
type: object
additionalProperties: true
description: Shows the XML data. If a search was triggered the hits are marked with `<exist:match xmlns:exist="http://exist.sourceforge.net/NS/exist">`.
application/json:
schema:
# oneOf:
$ref: '#/components/schemas/ObjectExtended'
# $ref: '#/components/schemas/PartList'
/api/{object-type}/{object-id}/{part-id}:
get:
tags:
- object
- search
summary: XML snippet for a specified passage in the object
description: |
Examples:
- A passage within a text: `/api/texts/M123456/p1.2.7`
- A page within a text: `/api/texts/M123456/page-1`
- A line within a text: `/api/texts/M123456/page-1.12`
parameters:
- name: object-type
in: path
description: ID of the object type
required: true
schema:
type: string
- name: object-id
in: path
description: ID of the object
required: true
schema:
type: string
- name: part-id
in: path
description: ID of the object
required: true
schema:
type: string
- $ref: '#/components/parameters/searchParam'
- $ref: '#/components/parameters/searchTypeParam'
- $ref: '#/components/parameters/searchXpathParam'
- $ref: '#/components/parameters/slopParam'
- $ref: '#/components/parameters/kwicWidthParam'
responses:
'200':
description: OK
content:
application/xml:
schema:
type: object
additionalProperties: true
description: Shows the XML data. If a search was triggered the hits are marked with `<exist:match xmlns:exist="http://exist.sourceforge.net/NS/exist">`.
example: |
<TEI xmlns="http://www.tei-c.org/ns/1.0" xml:space="preserve" xml:lang="en">
<text>
<body>
<div type="edition" n="text-01234">
<div type="book" n="2">
<div type="chapter" n="1">
<p>
<seg n="4"> Here is some text. All <exist:match xmlns:exist="http://exist.sourceforge.net/NS/exist">hits</exist:match> are marked.</seg>
</p>
</div>
</div>
</div>
</body>
</text>
</TEI>
components:
schemas:
ObjectGroup:
type: object
properties:
date-time:
type: string
format: date-time
description: stamp of caching
filter:
type: object
description: list of filters
additionalProperties:
$ref: '#/components/schemas/Filter'
list:
type: object
description: of objects
additionalProperties:
$ref: '#/components/schemas/Object'
type:
type: string
description: equals "object group"
example: manuscripts
results-found:
type: integer
description: number of all objects
example: 704
results-shown:
type: integer
description: number of objects in `list`. Equals to `results-found` if equal or lower then the `limit` parameter
example: 12
Filter:
type: object
properties:
id:
type: string
description: id of filter
example: library
name:
type: string
description: description of filter
example: Library which holds the manuscript
depends:
type: string
description: on which other filter it depends
example:
n:
type: integer
description: order number of filter
type:
type: string
description: type of filter
example: single
xpath:
type: string
description: to get the raw filter value
example: tei:repository
label-function:
type: string
description: function to get the processed filter value
example: function($string) { $string }
Object:
type: object
properties:
absolute-resource-id:
type: integer
description: object
example: 7096865764654
id:
type: string
description: of object
example: M012345
label:
type: string
description: main label of object
example: Manuscript No. 012345
label-filter:
type: array
description: values if defined
items:
type: string
labels:
type: array
description: list of labels of object
items:
type: string
example: [Manuscript No. 012345, Letter to myself]
filter:
type: object
description: list of object properties
properties:
id:
type: string
example: M012345
required:
- "id"
additionalProperties:
type: string
object-type:
type: string
description: type of object
example: manuscripts
search-results:
type: array
description: contains an array of hits, if a search was triggered.
items:
type: object
properties:
context-previous:
type: string
description: of the found keyword
example: "...n the text the searched "
keyword:
type: string
description: found by search
example: "word"
context-following:
type: string
description: of the found keyword
example: " is be found. And th..."
score:
type: number
format: float
description: of this single search hit
example: 0.26706398
part-id:
type: string
description: The ID of the related passage. Only retrieved by object API with `part-def` parameter.
example: book-1.2.7
score:
type: string
description: score of the search if triggered otherwise '0'
example: 0
ObjectExtended:
allOf:
- $ref: '#/components/schemas/Object'
- type: object
properties:
inner-nav:
type: object
description: list of defined inner navigations
additionalProperties:
type: object
properties:
id:
type: string
description: Where to find the IDs of items (XPath)
example: "@xml:id"
label-function:
type: string
description: label function of items (XQuery function)
example: function($node) { $node/string() }
list:
type: array
description: List of items.
items:
type: object
properties:
id:
type: string
description: ID of item
example: bibliography
label:
type: string
description: of item
example: Bibliography
name:
type: string
description: Name of inner-nav
example: Content
order-by:
type: string
description: how to order the items. If not set items are ordered by position in xml.
enum:
- label # order by label
xpath:
type: string
description: Where to find the inner-nav items (XPath)
example: tei:div[@type='main']
parts:
type: object
description: part definitions of object
additionalProperties:
type: object
properties:
depends:
type: string
description: On which other part definitions
example: book
id:
type: string
description: Definition of part id
example: "@n"
path:
type: string
description: Full path to part
example: book-<book>.<chapter>
root:
type: string
description: Definition of part root
example: "tei:div[@type='chapter']"
xmlid:
type: string
description: xml:id of part
example: book-chapter
views:
type: object
description: Contains the defined views of the object.
additionalProperties:
type: object
properties:
id:
type: string
description: ID of view
example: simple-view
label:
type: string
description: Label of view
example: Simple
params:
type: string
description: Defined parameter names for the view, separated bx ` `.
example: hightlight-persons
xslt:
type: string
description: Relative path to view xslt
example: resources/xslt/simple-view.xslt
PartList:
type: object
properties:
root:
type: string
description: XPath root of the part
example: tei:seg
path:
type: string
description: ID template for parts of this type
example: book-<book>.<book-chapter>.<book-chapter-segment>
depends:
type: string
description: The name of the hierarchical higher part
example: book-chapter
xmlid:
type: string
description: ID of the part definition
example: book-chapter-segment
id:
type: string
description: X-Path to the part id
example: "@n"
list:
type: array
items:
type: string
description: ID of an existing part
example: [ "book-1.1.1", "book-1.1.2", "book-1.1.3" ]
parameters:
searchParam:
name: search
in: query
description: Query expression to search within the object.
schema:
type: string
searchTypeParam:
name: search-type
in: query
description: To be used with `search`. If not set the exact matches are found. Multiple words are separated with a space.
schema:
type: string
enum:
- regex # for one or more words (separated by space) using regular expressions
- phrase # for a query of multiple words. With `slop` the distance can be defined (default is 1).
- lucene # for a lucene query, see <https://lucene.apache.org/core/2_9_4/queryparsersyntax.html>
searchXpathParam:
name: search-xpath
in: query
description: To be used with `search`. One can specify which xpath-Elements of the object are included in the search. They must be indexed, see [APPCONF.md](APPCONF.md).
schema:
type: string
slopParam:
name: slop
in: query
description: The distance of words in a phrase search. To be used with `search` and `search-type=phrase`.
schema:
type: integer
kwicWidthParam:
name: kwic-width
in: query
description: The range of characters shown before and after the match in the hit.
schema:
type: integer
example: 20