-
Notifications
You must be signed in to change notification settings - Fork 5
/
swagger.yaml
1109 lines (997 loc) · 34.7 KB
/
swagger.yaml
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
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: '3.0.2'
info:
title: ORR API Documentation
description: >
The main ORR documentation is located at: https://mmisw.org/orrdoc/
__Please note__:
- The ORR API is approaching a stable version but is still work in progress.
Please [let us know](https://github.com/mmisw/mmiorr-docs/issues) if you have any
questions or suggestions.
- Besides the documentation itself, this page lets you directly exercise and test the API.
Click on any operation header below to learn more details about it, and see a "Try it out" button.
- You can click on the "Authorize" button at the top right of this page
(or the `!` icon under the particular operation)
to retrieve an authentication token corresponding to your ORR instance credentials (username and password).
Once authorized, the authentication token will be automatically included in the corresponding request.
You will be able to not only perform the basic `GET` operations,
but also see expanded responses according to your access privileges
as well as perform other operations.
- The "Try it out" button will also show the corresponding API call that you can submit
from the command line using [`curl`](https://curl.haxx.se/).
- This API includes administrative operations related with the triple store.
The SPARQL endpoint itself
(located at `http://cor.esipfed.org/sparql` for the MMI ORR instance)
is not described here.
(General SPARQL information can be found [here](https://en.wikipedia.org/wiki/SPARQL),
and regarding the current service used by the ORR to support the SPARQL interface
[here](http://franz.com/agraph/support/documentation/current/http-protocol.html).)
- Actual requests from this page are against the specific endpoint at
`http://cor.esipfed.org/ont`.
termsOfService: 'https://marinemetadata.org/orr/tou'
contact:
name: 'COR API Support'
url: 'http://cor.esipfed.org'
email: '[email protected]'
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: http://cor.esipfed.org/v1
paths:
######################################################################
# Ontology
######################################################################
/ont/upload:
post:
tags: [ontology]
summary: Uploads an ontology file for subsequent registration
description: |
This operation allows to upload an ontology file as a preliminary step
for subsequent registration via a `POST /ont` request.
Before having to provide other required information for registration,
this separated step helps not only in determining that the file corresponds to an
ontology in a recognized format,
but also in terms of the returned associated information that the user or
client application can use for actual registration, for example, regarding possible
ontology IRIs found in the file.
operationId: uploadOnt
parameters:
- name: file
in: query
description: The file to be uploaded.
required: true
schema:
type: string
format: binary
- name: format
in: query
description: |
Format of the file.
The supported formats are described in [this section](https://mmisw.org/orrdoc/ontology/new/#supported-ontology-formats) of the documentation.
The special value `"_guess"` (without quotes)
can be given to let the ORR automatically determine the format.
(A future version of this API may allow this parameter to be omitted, in such
case implying the guess-format behavior.)
required: true
schema:
type: string
format: base64
responses:
'200':
description: |
Information about the uploaded file.
The `possibleOntologyIris` object will indicate the possible ontology IRI (or IRIs)
of the uploaded file. For each IRI, it will indicate some explanation for the
extraction of such IRI, and the associated metadata, if any.
On the other hand, the `userName` and `filename` attributes of
this object are to be used in the subsequent registration to properly refer to
the uploaded file.
An example of an actual response:
```
{
"userName": "carueda",
"filename": "1477537138555._guess",
"format": "rdf",
"possibleOntologyIris": {
"https://www.w3.org/ns/ssn": {
"explanations": [
"Resource of type http://www.w3.org/2002/07/owl#Ontology"
],
"metadata": {
"http://purl.org/dc/elements/1.1/title": [
"Semantic Sensor Network Ontology"
],
"http://www.w3.org/2000/01/rdf-schema#comment": [
"This ontology describes sensors and observations, and related concepts. It does not describe domain concepts, time, locations, etc. as these are intended to be included from other ontologies via OWL imports.",
"This ontology is based on the SSN Ontology by the W3C Semantic Sensor Networks Incubator Group (SSN-XG).",
"New modular version of the SSN ontology independent of DUL."
],
"http://www.w3.org/1999/02/22-rdf-syntax-ns#type": [
"http://www.w3.org/2002/07/owl#Ontology"
]
}
}
}
}
```
security:
- basicAuth: []
/ont:
get:
tags: [ontology]
summary: Gets information about registered ontologies or terms
description: |
General ontology or term report according to given parameters,
associated ontology visibility,
and privilege of the requesting user.
All parameters are optional.
Any given `iri`, `oiri`, or `tiri` parameter indicates a request for a
particular ontology or term.
If none of the `iri`, `oiri`, and `tiri` parameters is given,
this will indicate a query for a list of ontologies. In this case, only
a metadata summary is provided for each reported ontology (in particular,
no ontology contents per se is reported). Also, other supplied
parameters will be used to query for the desired ontologies.
For example, with the query paramenter and value `ownerName=acme`, all
ontologies owned by the `acme` organization will be considered for reporting.
parameters:
- name: iri
in: query
required: false
description: |
With this parameter the backend will first try an "ontology
request." If no ontlogy is registered by the given IRI, then it
will try a "term request."
schema:
type: string
format: base64
- name: oiri
in: query
required: false
description: |
Use this parameter to exclusively make a "ontology request."
schema:
type: string
format: base64
- name: version
in: query
required: false
description: |
Desired version in the case of an "ontology request."
schema:
type: string
format: base64
- name: tiri
in: query
required: false
description: |
Use this parameter to exclusively make a "term request."
schema:
type: string
format: base64
- name: format
in: query
required: false
description: |
Desired format for the response in the case of a single ontology or term request.
schema:
type: string
format: base64
responses:
'200':
description: Successful response
post:
tags: [ontology]
summary: Registers a brand new ontology
description: |
Performs the registration of a brand new ontology in the registry by
the IRI given in the `iri` attribute of the object in the body.
operationId: addOnt
parameters:
- in: query
name: body
description: |
Object with information for the ontology to be registered.
To provide the contents of the ontology you have two options:
- Specify a previously uploaded file (via `POST /ont/upload`) by
providing the corresponding reported filename (in the `uploadedFilename`
field) and format (`uploadedFormat`). There's no need to upload the file
itself again.
- Embbed the complete contents in the `contents` field, and provide the associated
format in `format`.
See the `PostOnt` object description for more details.
schema:
$ref: "#/components/schemas/PostOnt"
required: true
responses:
"405":
description: Invalid input
security:
- basicAuth: []
put:
tags: [ontology]
summary: Updates a given ontology version or adds a new version
description: |
Use this operation to create a new version for a registered ontology,
or to update an exisiting version.
operationId: updateOnt
parameters:
- in: query
name: body
description: |
Ontology object that needs to be registered.
Provide the `metadata` attribute to create a new version of
an existing ontology solely based on changes on the metadata.
For full contents, use `contents`/`format`, or
`uploadedFilename`/`uploadedFormat` as described in the `POST /ont`
operation.
schema:
$ref: "#/components/schemas/PutOnt"
responses:
"405":
description: Invalid input
security:
- basicAuth: []
delete:
tags: [ontology]
summary: Deletes a particular version or a whole ontology entry
description: |
This operation allows to unregister a particular version (if the
`version` object attribute is given) or a whole ontoloy entry.
Besides admins, only an owner of the ontology can perform this
operation.
operationId: deleteOnt
parameters:
- in: query
name: iri
description: Ontology IRI
required: true
schema:
type: string
format: base64
- in: query
name: version
description: |
Particular version to be deleted.
If omitted, the whole entry by the given IRI will be unregistered.
schema:
type: string
format: base64
- in: query
name: userName
required: true
description: |
Registered user making the request. Must be an owner of the ontology.
schema:
type: string
format: base64
responses:
"405":
description: Invalid input
security:
- basicAuth: []
/ont/term:
post:
tags: [ontology, term]
summary: Adds a term to an existing ORR vocabulary
description: |
This operation allows to add a new term to an ORR vocabulary.
This addition does not generate a new version of the vocabulary.
operationId: addTerm
parameters:
- in: query
name: body
description: |
Object with information for the term to be added.
See the `PostOnt` object description for more details.
schema:
$ref: "#/components/schemas/PostTerm"
required: true
responses:
"405":
description: Invalid input
security:
- basicAuth: []
######################################################################
# Organization
######################################################################
/org:
get:
tags: [organization]
summary: Gets information about registered organizations
description: |
Gets basic information of all registered organizations.
This will include additional information depending on privileges of requesting user.
responses:
'200':
description: Successful response
post:
tags: [organization]
summary: Registers an organization
description: |
Only admins can perform this operation.
operationId: addOrg
parameters:
- in: query
name: body
description: Organization object that needs to be registered
schema:
$ref: "#/components/schemas/PostOrg"
responses:
"201":
description: Successful registration
"405":
description: Invalid input
security:
- basicAuth: []
'/org/{orgName}':
get:
tags: [organization]
summary: Gets basic information of a particular organization
parameters:
- name: orgName
in: path
required: true
description: The code (short name) of the organization.
schema:
type: string
format: base64
responses:
'200':
description: Successful response
put:
tags: [organization]
summary: Updates information about a registered organization
operationId: updateOrg
parameters:
- name: orgName
in: path
required: true
description: The code (short name) of the organization to be updated.
schema:
type: string
format: base64
- in: query
name: body
description: Object with information for the organization to be updated.
schema:
$ref: "#/components/schemas/PutOrg"
responses:
"200":
description: Successful update
"405":
description: Invalid input
security:
- basicAuth: []
delete:
tags: [organization]
summary: Unregisters an organization
description: |
Only users with administrative privilege can perform this operation.
operationId: deleteOrg
parameters:
- in: path
name: orgName
description: Identifier of the organization
required: true
schema:
type: string
format: base64
responses:
"200":
description: Successful unregistration
"404":
description: No such organization
security:
- basicAuth: []
######################################################################
# User
######################################################################
/user:
get:
tags: [user]
summary: Gets information about registered users
description: |
Gets information about registered users.
This will include additional information depending on privileges of requesting user.
responses:
'200':
description: Successful response
post:
tags: [user]
summary: Registers a user
description: |
This operation allows to register a new user in the system.
**NOTE**: This operation cannot be completed here if the endpoint is configured to
required a ReCAPTCHA code, which is currently not captured in this interface.
Please use the ORR Portal interface associated with the endpoint to register
the new user.
operationId: addUser
parameters:
- in: query
name: body
description: User object that needs to be registered
schema:
$ref: "#/components/schemas/PostUser"
responses:
"400":
description: |
If the endpoint is configured to require a ReCAPTCHA code,
which is not captured in this API interface.
"405":
description: Invalid input
'/user/{userName}':
get:
tags: [user]
summary: Gets basic information of a particular user
parameters:
- name: userName
in: path
required: true
description: The login (short name) of the user.
schema:
type: string
format: base64
responses:
'200':
description: Successful response
put:
tags: [user]
summary: Updates information about a registered user
description: |
Only the same user and users with administrative privilege can perform this operation.
operationId: updateUser
parameters:
- name: userName
in: path
required: true
description: The identifier of the user to be updated.
schema:
type: string
format: base64
- in: query
name: body
description: Object with information for the user to be updated.
schema:
$ref: "#/components/schemas/PutUser"
responses:
"405":
description: Invalid input
security:
- basicAuth: []
delete:
tags: [user]
summary: Unregisters a user
description: |
Only users with administrative privilege can perform this operation.
operationId: deleteUser
parameters:
- in: path
name: userName
description: Identifier of the user
required: true
schema:
type: string
format: base64
responses:
"200":
description: Successful unregistration
"404":
description: No such user
security:
- basicAuth: []
######################################################################
# Term search
######################################################################
/term:
get:
tags: [term]
summary: Simplified semantic search queries against the triple store
description: |
This endpoint route is intended to provide some common semantic search
operations against the triple store.
**NOTE**: This is an experimental operation.
The SPARQL interface remains the most complete and powerful semantic search mechanism.
Provide one of `containing` or `predicate` as main parameter, along with associated
auxiliary and optional parameters as described.
parameters:
- name: containing
in: query
required: false
description: |
Searches the given string in the indicated parts of the triples as
determined by the `in` parameter.
schema:
type: string
format: base64
- name: in
in: query
required: false
description: |
Only used in combination with the `containing` parameter, the `in` parameter
determines where to perform the search: subject, predicate, and/or object.
Use the 1-character abbreviations: `s` for subject, `p` for predicate, `o` for object.
Any combination of these characters can be used as value for the `in` parameter.
For example, to search the given `containing` string in all parts of the triple use `spo`.
The default value is `s`, meaning the search will only be on the subject.
schema:
type: string
format: base64
- name: predicate
in: query
required: false
description: |
Desired predicate to retrieve entities related with a given subject or object.
The following common namespace prefixes are recognized:
`skos:`, `owl:`, `rdfs:`, `rdf:`.
So possible values of this parameter include `skos:relatedMatch` and `owl:sameAs`.
If the value does not start with any of the recognized prefixes, then it is assumed
to be a full IRI, e.g., `http://purl.org/dc/terms/description`.
This parameter is to be used in combination with one of the `subject` or `object` parameters.
If `subject` is given, the underlying SPARQL query is basically
`<subject> <predicate> ?object` and the resulting list of objects is returned.
Otherwise the underlying SPARQL query is basically
`?subject <predicate> <object>` and the resulting list of subjects is returned.
schema:
type: string
format: base64
- name: subject
in: query
required: false
description: |
IRI of the subject for underlying SPARQL query.
Required when any of the _predicate_ parameters is given and **no** object parameter is given.
schema:
type: string
format: base64
- name: object
in: query
required: false
description: |
IRI of the object for underlying SPARQL query.
Required when any of the _predicate_ parameters is given and **no** subject parameter is given.
schema:
type: string
format: base64
- name: limit
in: query
required: false
description: |
Maximum number of solutions to be returned.
The default value is 30.
A non-positive value means no limit, so all solutions will be returned.
schema:
type: integer
format: int32
- name: offset
in: query
required: false
description: |
Solutions returned will start after the specified number of solutions.
Ignored if the value is non-positive.
By default, no offset.
schema:
type: integer
format: int32
responses:
'200':
description: Successful response
######################################################################
# Triplestore
######################################################################
/ts:
get:
tags: [triplestore]
summary: Gets the size of the store or the size of a particular named graph
description: |
Provide one of the `iri` or `context` parameters to get the size of a particular graph.
If none of these parameters is provided, the size of the whole triplestore will be responded.
Only admins can perform this operation.
operationId: getTriplestoreSize
parameters:
- name: iri
in: query
required: false
description: |
IRI of particular context
schema:
type: string
format: base64
- name: context
in: query
required: false
description: |
IRI of particular context
schema:
type: string
format: base64
responses:
'200':
description: Successful response
post:
tags: [triplestore]
summary: Loads an ontology in the triplestore
description: |
Only admins can perform this operation.
operationId: loadOntInTriplestore
parameters:
- name: iri
in: query
required: true
description: |
IRI of the ontology to be loaded
schema:
type: string
format: base64
responses:
"200":
description: Successful operation
"405":
description: Invalid input
security:
- basicAuth: []
put:
tags: [triplestore]
summary: Reloads an ontology or all ontologies in the triplestore
description: |
Provide the `iri` parameter to reload a particular ontology.
Otherwise all registered ontologies will be reloaded in the triplestore.
Only admins can perform this operation.
operationId: reloadOntsInTriplestore
parameters:
- name: iri
in: query
required: false
description: |
IRI of the ontology to be reloaded
schema:
type: string
format: base64
responses:
"200":
description: Successful operation
"405":
description: Invalid input
security:
- basicAuth: []
delete:
tags: [triplestore]
summary: Unloads an ontology or all ontologies from the triplestore
description: |
Provide the `iri` parameter to unload a particular ontology.
Otherwise all registered ontologies will be unloaded from the triplestore.
Only admins can perform this operation.
operationId: unloadOntsInTriplestore
parameters:
- name: iri
in: query
required: false
description: |
IRI of the ontology to be unloaded
schema:
type: string
format: base64
responses:
"200":
description: Successful operation
"405":
description: Invalid input
security:
- basicAuth: []
components:
schemas:
######################################################################
# Ontology
######################################################################
UploadedFileInfo:
type: object
properties:
userName:
type: string
description: The user that requested the upload.
filename:
type: string
description: The name associated with the file.
format:
type: string
description: The format of the file.
possibleOntologyIris:
type: object
description: The format of the file.
PossibleOntologyInfo:
type: object
properties:
explanations:
type: array
items:
type: string
description: |
Explanations for the extraction of the given possible ontology IRI.
metadata:
type: object
description: Metadata associated to the ontology IRI.
additionalProperties:
type: array
items:
type: string
PostOnt:
type: object
properties:
iri:
type: string
description: |
The IRI of the ontology.
originalIri:
type: string
description: |
In case of a fully-hosted registration, enter this field to indicate
the original IRI in the provided contents to be used for the "migration"
of corresponding entities to the new IRI.
name:
type: string
description: |
The name for the ontology. If omitted, the ORR will try to get this
information from standard metadata in the submitted ontology contents.
orgName:
type: string
description: |
ID of the organization that will own the ontology registration.
If omitted, the owner will be the submitting user.
visibility:
type: string
description: |
One of: `owner` or `public`. The default visibility is `owner`.
status:
type: string
description: |
One of: `draft`, `unstable`, `testing`, `stable`, `deprecated`, `archaic`.
There's no default value.
userName:
type: string
description: |
Registered user making the request.
uploadedFilename:
type: string
description: |
Name of file previously uploaded via prior `POST /ont/upload` request.
uploadedFormat:
type: string
description: |
Format of the file previously uploaded via prior `POST /ont/upload` request.
contents:
type: string
description: |
Direct contents of the ontology.
format:
type: string
description: |
Format of the `contents`.
PutOnt:
type: object
properties:
iri:
type: string
description: The IRI of the ontology to be updated.
version:
type: string
description: |
If given, this particular version will be updated.
Otherwise, a new version (which is generated by the ORR) is created.
originalIri:
type: string
description: |
In case a fully-hosted registration and ontology contents are provided for this update, enter this field to indicate
the original IRI to be used for the "migration" of corresponding entities to the IRI used for registration.
name:
type: string
description: |
If given, this will be the new name for the ontology.
visibility:
type: string
description: |
One of: `owner` or `public`.
status:
type: string
description: |
One of: `draft`, `unstable`, `testing`, `stable`, `deprecated`, `archaic`.
metadata:
type: string
description: |
Ontology metadata as a JSON formatted object.
This parameter allows to perform the update solely based on changes
to the metadata.
uploadedFilename:
type: string
description: |
Name of file previously uploaded via prior `POST /ont/upload` request.
uploadedFormat:
type: string
description: |
Format of the file previously uploaded via prior `POST /ont/upload` request.
contents:
type: string
description: |
Direct contents of the ontology.
format:
type: string
description: |
Format of the `contents`.
userName:
type: string
description: |
Registered user making the request.
PostTerm:
type: object
properties:
vocIri:
type: string
description: |
The IRI of the affected ORR vocabulary.
version:
type: string
description: |
The version to be affected. By default, latest version.
classIri:
type: string
description: |
IRI of the specific class to be affected within the vocabulary.
Can be ommitted if the vocabulary only contains one class (which
will be the one affected).
termName:
type: string
description: |
Simple name of the new term.
termIri:
type: string
description: |
Full IRI of the new term.
attributes:
type: array
items:
type: array
items:
type: string
description: |
Values for the properties defined for the vocabulary class.
Ont:
type: object
properties:
iri:
type: string
name:
type: string
version:
type: string
ownerName:
type: string
status:
type: string
format:
type: string
visibility:
type: string
######################################################################
# Organization
######################################################################
PostOrg:
type: object
properties:
name:
type: string
orgName:
type: string
members:
type: array
items:
type: string
description: Members of this organization
url:
type: string
description: Website URL of the organization
PutOrg:
type: object
properties: