-
Notifications
You must be signed in to change notification settings - Fork 10
/
linked-events.swagger.yaml
1365 lines (1325 loc) · 53.8 KB
/
linked-events.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
---
swagger: '2.0'
info:
title: Linked Events information API
description: |-
Linked Events provides categorized data on events and places using JSON-LD format.
Events can be searched by date and location. Location can be exact address or larger
area such as neighbourhood or borough
JSON-LD format is streamlined using include mechanism. API users can request that certain
fields are included directly into the result, instead of being hyperlinks to objects.
Several fields are multilingual. These are implemented as object with each language variant
as property. In this specification each multilingual field has (fi,sv,en) property triplet as
example.
termsOfService: (depends on data provider)
version: v1
# Helsinki implementation is ok for seeing how API works. It has extra fields and endpoints
# compared to this specification
host: api.hel.fi
basePath: /linkedevents/v1
schemes:
- https
- http
produces:
- application/json
tags:
- name: event
description: Search and Edit events
- name: filter
description: Search for keywords and places for filtering events
- name: search
description: Fulltext search through events and places
- name: language
description: Get supported languages
- name: image
description: Get and upload images
parameters:
page_param:
name: page
in: query
description: request particular page in paginated results
required: false
type: integer
pagesize_param:
name: page_size
in: query
description: request that server delivers page_size results in response
required: false
type: integer
sort:
name: sort
in: query
description: return the results in ascending or descending order by the named field. sorting is only supported for some string, integer and datetime fields.
required: false
type: string
event_sort_param:
name: sort
in: query
type: string
description: Sort the returned events in the given order. Possible sorting criteria are 'start_time', 'end_time', 'days_left' and 'last_modified_time'. The default ordering is '-last_modified_time'.
place_sort_param:
name: sort
in: query
type: string
description: Sort the returned places in the given order. Possible sorting criteria are 'n_events', 'id', 'name', 'street_address' and 'postal_code'. The default ordering is '-n_events'.
keyword_sort_param:
name: sort
in: query
type: string
description: Sort the returned keywords in the given order. Possible sorting criteria are 'n_events', 'id', 'name', 'data_source'. The default ordering is '-data_source', '-n_events'.
include_param:
name: include
in: query
type: array
items:
type: string
description: Embed given reference-type fields directly into the response, otherwise they are returned as URI references.
event_text_param:
name: text
in: query
description: Search (case insensitive) through all multilingual text fields (name, description, short_description, info_url) of an event (every language). Multilingual fields contain the text that users are expected to care about, thus multilinguality is useful discriminator.
required: false
type: string
event_last_modified_param:
name: last_modified_since
in: query
description: Search for events that have been modified since or at this time.
type: string
format: dateTime
event_bbox_param:
name: bbox
in: query
type: array
items:
type: string
minItems: 4
maxItems: 4
description: Search for events that are within this bounding box. Decimal coordinates are given in order west, south, east, north. Period is used as decimal separator.
event_start_param:
name: start
in: query
type: string
format: date-time
description: Search for events beginning or ending after this time. Dates can be specified using ISO 8601 ("2016-01-12") and additionally "today".
event_end_param:
name: end
in: query
type: string
format: date-time
description: Search for events beginning or ending before this time. Dates can be specified using ISO 8601 ("2016-01-12") and additionally "today".
event_data_source_param:
name: data_source
in: query
type: string
description: Search for events that come from the specified source system
event_location_param:
name: location
in: query
type: array
items:
type: integer
description: Search for events in given locations as specified by id. Multiple ids are separated by comma
event_keyword_param:
name: keyword
in: query
type: string
description: Search for events with given keywords as specified by id. Multiple ids are separated by comma
event_recurring_param:
name: recurring
in: query
type: string
enum:
- super
- sub
description: Search for events based on whether they are part of recurring event set. 'super' specifies recurring, while 'sub' is non-recurring.
event_min_duration_param:
name: min_duration
in: query
type: integer
description: Search for events that are longer than given time in seconds
event_max_duration_param:
name: max_duration
in: query
type: integer
description: Search for events that are shorter than given time in seconds
event_organization_param:
name: publisher
in: query
type: string
description: Search for events published by the given organization
definitions:
meta_definition:
title: Meta
description: Meta record for result pagination. All results from API are paginated, ie. delivered in chunks of X results. This records describes how many results there are in total, and how to access previous and next pages.
type: object
properties:
count:
description: Total amount of items found
type: integer
next:
description: URL for the next page of items
type: string
format: url
previous:
description: URL for the previous page of items
type: string
format: url
place:
type: object
title: Place
description: Places describe physical locations for events and means for contacting people responsible for these locations. Place definitions come from organizations publishing events (field "publisher") and can thus have slightly different semantics between places sourced from different organizations.
required:
- name
- position
properties:
id:
type: string
description: Consists of source prefix and source specific identifier. These should be URIs uniquely identifying the place, and preferably also well formed http-URLs pointing to more information about the place.
custom_data:
type: array
description: 'Key value field for custom data. FIXME: is there 6Aika-wide use case for this?'
items:
type: object
properties:
key:
type: string
value:
type: string
name:
type: object
description: Name of the place, multilingual
properties:
fi:
type: string
description: place name in Finnish
sv:
type: string
description: place name in Swedish
en:
type: string
description: place name in English
images:
type: array
items:
"$ref": '#/definitions/image'
origin_id:
type: string
description: 'Place identifier in the originating system, these should be in same format as id but variations are more likely than with id.'
created_time:
type: string
format: date-time
description: 'Creation time for the place entry.'
last_modified_time:
type: string
format: date-time
description: 'Time this place was modified in the datastore behind the API (not necessarily in the originating system)'
# No examples of the translated representation, probably same as with other multilingual fields.
info_url:
description: Link (URL) to a page with more information about place
type: object
properties:
fi:
description: Link to Finnish page
type: string
format: url
se:
description: Link to Swedish page
type: string
format: url
en:
description: Link to English page
type: string
format: url
description:
description: 'Short (? FIXME: perhaps specify recommendation) description of the place, multilingual.'
type: object
properties:
fi:
type: string
description: place description in Finnish
sv:
type: string
description: place description in Swedish
en:
type: string
description: place description in English
position:
description: geographic position of the place specified using subset of GeoJSON
type: object
properties:
coordinates:
description: coordinates in format specified by type property
type: array
items:
type: number
type:
description: interpretation of the coordinates property. Only point is supported in this version
type: string
enum:
- Point
email:
type: string
description: Contact email for the place, note that this is NOT multilingual
telephone:
type: object
description: Contact phone number for the place, multilingual
properties:
fi:
type: string
description: phone number for Finnish speakers
sv:
type: string
description: phone number for Swedish speakers
en:
type: string
description: phone number for English speakers
contact_type:
type: string
description: 'FIXME: this seems unused in Helsinki data. Does any 6Aika city have use for describing contact type?'
street_address:
description: Street address for the place, multilingual
type: object
properties:
fi:
type: string
description: address in Finnish
sv:
type: string
description: address in Swedish
en:
type: string
description: address in English
address_locality:
description: Describes where the address is located, typically this would be name of the city
type: object
properties:
fi:
type: string
description: locality in Finnish
sv:
type: string
description: locality in Swedish
en:
type: string
description: locality in English
address_region:
type: string
description: Larger region for address (like states), not typically used in Finland
postal_code:
type: string
description: Postal code of the location (as used by traditional mail)
post_office_box_num:
type: string
description: PO box for traditional mail, in case mail is not delivered to the building
address_country:
type: string
description: Country for the place, NOT multilingual
deleted:
type: boolean
description: This place entry is not used anymore, but old events still reference it. This might be because of duplicate removal.
data_source:
type: string
description: Identifies the source for data, this is specific to API provider. This is useful for API users, as any data quality issues are likely to be specific to data source and workarounds can be applied as such.
publisher:
type: string
description: Organization that provided the event that this place is associated with
image:
title: Image
description: Images are used as pictures for events, places and organizers.
type: object
required:
- url
properties:
name:
type: object
properties:
fi:
type: string
description: Image description in Finnish
sv:
type: string
description: Image description in Swedish
en:
type: string
description: Image description in English
publisher:
type: string
description: The organization responsible for the image.
created_time:
type: string
format: date-time
description: 'Creation time for the image.'
last_modified_time:
type: string
format: date-time
description: 'Time this image was modified in the datastore behind the API (not necessarily in the originating system)'
created_by:
type: string
description: URL reference to the user that created this record (user endpoint)
last_modified_by:
type: string
description: URL reference to the user that last modfied this record (user endpoint)
url:
type: string
description: The image file URL.
cropping:
type: string
description: Cropping data for the image.
license:
type: string
description: License data for the image. May be "cc_by" (default) or "event_only". The latter license restricts use of the image and is specified on the API front page.
keyword:
title: Keyword
description: Keywords are used to describe events. Linked events uses namespaced keywords in order to support having events from different sources. Namespaces are needed because keywords are defined by the organization sourcing the events and can therefore overlap in meaning. Conversely the meaning of same keyword can vary between organizations. Organization sourcing the keyword can be identified by data_source field. Data_source field will later specify standardized namespaces as well.
type: object
required:
- id
- name
- data_source
properties:
id:
type: string
description: Consists of source prefix and source specific identifier. These should be URIs uniquely identifying the keyword, and preferably also well formed http-URLs pointing to more information about the keyword.
name:
type: object
properties:
fi:
type: string
description: Keyword in Finnish
sv:
type: string
description: Keyword in Swedish
en:
type: string
description: Keyword in English
images:
type: array
items:
"$ref": '#/definitions/image'
origin_id:
type: string
description: Identifier for the keyword in the organization using this keyword. For standardized namespaces this will be a shared identifier.
created_time:
type: string
format: date-time
description: 'Creation time for the keyword entry.'
last_modified_time:
type: string
format: date-time
description: 'Time this place was modified in the datastore behind the API (not necessarily in the originating system)'
aggregate:
type: boolean
description: FIXME(verify) This keyword is an combination of several keywords at source
data_source:
type: string
description: Source of the keyword, typically API provider specific identifier. Will also be used to specify standardized namespaces as they are brought into use.
created_by:
type: string
description: FIXME(verify) URL reference to the user that created this record (user endpoint)
last_modified_by:
type: string
description: FIXME(verify) URL reference to the user that last modfied this record (user endpoint)
alt_labels:
type: array
items:
type: string
description: FIXME(verify) alternative labels for this keyword, no language specified. Use case?
keyword_set:
title: Keyword set
description: Keyword sets are used to group keywords together into classification groups. For example, one set of keywords might describe themes used by an event provider and another could be used to describe audience groups.
type: object
required:
- id
- name
- keywords
properties:
id:
type: string
description: Unique identifier for this keyword_set. These should be URIs identifying the source and the keyword_set itself, and preferably also well formed http-URLs pointing to more information about the keyword.
name:
type: string
description: Name for this keyword_set. This should be human readable, such that it could be shown as label in UI
origin_id:
type: string
description: 'Set identifier in the originating system, if any'
created_time:
type: string
format: date-time
description: Time when this keyword_set was created (ISO 8601)
last_modified_time:
type: string
format: date-time
description: Time when this keyword_set was last modified (ISO 8601)
data_source:
type: string
description: Unique identifier (URI)for the system where this keyword_set originated, if any
last_modified_by:
type: string
description: FIXME(verify) Which API user most recently edited this keyword
usage:
type: string
description: 'Usage type for this keyword_set. These are allow UIs to show the set in appropriate place. FIXME: set of types is not finalized by any stretch'
enum:
- any
- keyword
- audience
organization:
type: string
description: Organization that has defined this keyword_set
keywords:
type: array
description: Keywords that belong to this keyword_set
items:
"$ref": '#/definitions/keyword'
language:
title: Languages supported in this API
type: object
description: Primary purpose of this endpoint is to allow users to identify which languages are supported for multilingual fields. It also has translations for the names of the languages.
required:
- id
- name
properties:
id:
type: string
description: Identifier for the language (typically ISO639-1)
name:
type: object
description: Translation for the language name. Properties shown here are examples, it is suggested that every language supported has its name translated to every other language. Users of the API cannot rely on any translations being present.
properties:
fi:
description: Name of the language in Finnish
type: string
se:
description: Name of the language in Swedish
type: string
en:
description: Name of the language in English
type: string
event:
title: Events
type: object
description: 'Describes the actual events. Linked events API supports organizing events into hierarchies. This is implemented with collection events called "super events". Super events are normal event objects, that reference contained events in "sub_events" property. Currently there are two major use cases: events such as "Helsinki Festival", which consist of unique events over a span of time and recurring events such as theatrical productions with multiple showings. It is implementation dependent how the grouping of events is done. It should be noted that grouping might be automatic based on eg. event name and thus group unrelated events together and miss related events. Users of data are advised to prepare for this.'
required:
- name
- location
- start_time
- keywords
- publication_status
properties:
id:
description: consists of source prefix and source specific identifier. These should be URIs uniquely identifying the event, and preferably also well formed http-URLs pointing to more information about the event.
type: string
location:
"$ref": '#/definitions/place'
keywords:
description: array of keyword uri references
type: array
items:
type: string
format: uri
in_language:
description: the languages spoken or supported at the event
type: array
items:
"$ref": '#/definitions/language'
super_event:
description: references the aggregate event containing this event
type: string
super_event_type:
description: If the event has sub_events, describes the type of the event. Current options are 'null' and 'recurring', which means a repeating event.
type: string
event_status:
type: string
description: As defined in schema.org/Event. Postponed events do not have a date set, rescheduled events have been moved to different date.
publication_status:
type: string
description: Only available in POST/PUT. Specifies whether the event should be published in the API ('public') or not ('draft').
external_links:
type: array
items:
"$ref": '#/definitions/eventlink'
description: See external link definition
offers:
type: array
items:
"$ref": '#/definitions/offer'
description: See offer definition
sub_events:
type: array
items:
type: string
description: for aggregate events this contains references to all sub events. Usually this means that the sub events are part of series. The field 'super_event_type' tells the type of the aggregate event.
custom_data:
type: string
description: 'Key value field for custom data. FIXME: is there 6Aika-wide use case for this?'
name:
type: object
description: 'Short descriptive name for the event, recommended limit: 80 characters'
properties:
fi:
description: Name of the event in Finnish
type: string
se:
description: Name of the event in Swedish
type: string
en:
description: Name of the event in English
type: string
images:
type: array
items:
"$ref": '#/definitions/image'
created_time:
type: string
format: date-time
description: 'Creation time for the event entry.'
last_modified_time:
type: string
format: date-time
description: 'Time this event was modified in the datastore behind the API (not necessarily in the originating system)'
info_url:
description: Link (URL) to a page with more information about event
type: object
properties:
fi:
description: Link to Finnish page
type: string
format: url
se:
description: Link to Swedish page
type: string
format: url
en:
description: Link to English page
type: string
format: url
description:
type: object
description: Description for the event, several chapters(FIXME, verify)
properties:
fi:
description: Finnish description of the event
se:
description: Swedish description of the event
en:
description: English description of the event
short_description:
type: object
description: Short description for the event, recommended limit 140 characters
properties:
fi:
description: short Finnish description of the event
se:
description: short Swedish description of the event
en:
description: short English description of the event
date_published:
type: string
format: date-time
description: Date this event is free to be published
provider:
type: object
description: organization responsible for the practical implementation of the event
properties:
fi:
description: provider name in Finnish for the event
se:
description: provider name in Swedish for the event
en:
description: provider name in English for the event
location_extra_info:
type: object
description: Unstructured extra info about location (like "eastern door of railway station")
properties:
fi:
description: location extra info in Finnish for the event
se:
description: location extra info in Swedish for the event
en:
description: location extra info in English for the event
start_time:
type: string
format: date-time
description: Time the event will start
end_time:
type: string
format: date-time
description: Time the event will end
audience:
type: array
items:
"$ref": '#/definitions/keyword'
data_source:
type: string
description: Unique identifier (URI)for the system from which this event came from, preferably URL with more information about the system and its policies
created_by:
type: string
description: FIXME(verify) Which API user created this keyword
last_modified_by:
type: string
description: FIXME(verify) Which API user most recently edited this keyword
publisher:
type: string
description: Organization responsible for this event record.
offer:
title: Price offers
description: information record for this event. The prices are not in a structured format and the format depends on information source. An exception to this is the case of free event. These are indicated using is_free flag, which is searchable.
type: object
properties:
price:
type: object
description: Price of the event. These are not bare numbers but instead descriptions of the pricing scheme.
properties:
fi:
type: string
description: Finnish translation for the price information
sv:
type: string
description: Swedish translation for the price information
en:
type: string
description: English translation for the price information
info_url:
description: Link (URL) to a page with more information about offer
type: object
properties:
fi:
description: Link to Finnish page
type: string
format: url
se:
description: Link to Swedish page
type: string
format: url
en:
description: Link to English page
type: string
format: url
description:
type: object
description: Further description of the pricing
properties:
fi:
type: string
description: Finnish price description
sv:
type: string
description: Swedish price description
en:
type: string
description: English price description
is_free:
type: boolean
description: Whether the event is of free admission
eventlink:
title: Links to related information
description: Links to entities that the event publisher considers related to this event. Eg. links to catering service available during theatrical production. The links will most likely point to unstructured content, ie. web pages suitable for human viewing.
type: object
properties:
name:
type: string
description: Name describing contents of the link
link:
type: string
description: link to an external related entity
language:
type: string
description: language of the content behind the link
paths:
/search/:
get:
summary: Search through events and places
description: |
<h2 id="using-search-endpoint">Using the search endpoint</h2>
<p>This is the supposedly intelligent Elasticsearch Finnish full-text search for both events and places.
The results are sorted by relevance score shown in the <code>score</code> field. The search parameter is <code>?q=</code>.
<h4 id="specifying-resource-type">Specifying resource type</h4>
<p>In the default case, both events and places are returned. The type of each resource is returned in the
<code>resource_type</code> field. You may use the parameter <code>type</code> to ask for only <code>event</code> or <code>place</code>.
<h4 id="events-with-decay-score">Future events with time decay</h4>
<p>When searching for events only (<code>?type=event</code>), by default only future events are returned, with a decay function applied so that next
events get a higher relevance score. This means that
events in the near future are returned first:</p>
<pre><code>search/?type=event&q=sibelius
</code></pre>
<p><a href="?type=event&q=sibelius" title="json">See the result</a></p>
<h4 id="events-with-time-filtering">Events with time filtering</h4>
<p>When searching for events only (<code>?type=event</code>), you may also search for events in the specified time range using
<code>start</code> or <code>end</code> or both. In this case, relevance score
is calculated only based on Finnish tokenization of the search string, with no time preference:</p>
<pre><code>search/?type=event&q=sibelius&start=2017-01-01
</code></pre>
<p><a href="?type=event&q=sibelius&start=2017-01-01" title="json">See the result</a></p>
<h4 id="autocomplete">Autocomplete</h4>
<p>For fast autocomplete substring match in the resource name, use the <code>?input=</code> parameter instead.
When searching for events only (<code>?type=event</code>), by default only future events are returned, with a decay function applied so that next
events get a higher relevance score. May be combined with <code>start</code> and <code>end</code>.
<pre><code>search/?type=place&input=sibe
</code></pre>
<p><a href="?type=event&input=sibe" title="json">See the result</a></p>
operationId: event_search
tags:
- search
parameters:
- $ref: '#/parameters/page_param'
- $ref: '#/parameters/pagesize_param'
- name: type
in: query
type: string
description: Comma-delimited list of resource types to search for. Currently allowed values are `event` and `place`. `type=event` must be specified for event date filtering and relevancy sorting.
- name: q
in: query
type: string
description: Search for events and places matching this string. Mutually exclusive with `input` typeahead search.
- name: input
in: query
type: string
description: Return autocompletition suggestions for this string. Mutually exclusive with `q` full-text search.
- $ref: '#/parameters/event_start_param'
- $ref: '#/parameters/event_end_param'
responses:
200:
description: List of resources
schema:
type: object
properties:
meta:
$ref: '#/definitions/meta_definition'
data:
type: array
items:
$ref: '#/definitions/event'
/image/:
get:
summary: Returns a list of images
description: |
Image endpoint returns images that are used for events, places or organizers.
operationId: image_list
tags:
- image
parameters:
- $ref: '#/parameters/page_param'
- $ref: '#/parameters/pagesize_param'
- $ref: '#/parameters/include_param'
- $ref: '#/parameters/sort'
responses:
200:
description: List of images
schema:
type: object
properties:
meta:
$ref: '#/definitions/meta_definition'
data:
type: array
items:
$ref: '#/definitions/image'
post:
summary: Create a new image
operationId: image_create
description: There are two ways to create an image object. The image file can be posted as a multipart request, but the endpoint also accepts a simple JSON object with an external url in the url field. This allows using external images for events without saving them on the API server.
tags:
- image
consumes:
- multipart/form-data
responses:
201:
description: Object has been succesfully created. A copy of the object is returned in response body and headers contain Location pointing to the created event
schema:
$ref: '#/definitions/image'
400:
description: Input format was not correct, eg. mandatory field was missing or JSON was malformed
401:
description: User was not authenticated
403:
description: User does not have necessary permissions
parameters:
- name: image_file
in: formData
type: file
/image/{id}/:
get:
summary: Return information for single image
operationId: image_retrieve
tags:
- image
responses:
200:
description: Image record
schema:
$ref: '#/definitions/image'
parameters:
- type: string
description: The id for the image
in: path
name: id
required: true
put:
summary: Update an image
description: Images can be updated if the user has appropriate access permissions. The original implementation behaves like PATCH, ie. if some field is left out from the PUT call, its value is retained in database. In order to ensure consistent behaviour, users should always supply every field in PUT call.
operationId: image_update
tags:
- image
responses:
200:
description: Image has been succesfully replaced
schema:
$ref: '#/definitions/image'
400:
description: Input format was not correct, eg. mandatory field was missing or JSON was malformed
401:
description: User was not authenticated
403:
description: User does not have necessary permissions
parameters:
- type: string
in: path
name: id
required: true
description: Identifier for the image to be updated
- name: image_object
in: body
description: Image object that should replace the existing image, note that some implementations may retain unspecified fields at their original values.
schema:
$ref: '#/definitions/image'
/keyword/:
get:
summary: Returns a list of keywords used for describing events
description: |
<h2 id="using-keyword-endpoint">Using the keyword endpoint</h2>
<p>Here, categories for events are listed. Events in each category can be found at the
<code>event</code> endpoint using the query parameter <code>keyword</code>. The common keywords
used in all events originate from the <a href="https://finto.fi/yso/en/">general Finnish ontology (yso)</a>,
hence the format <code>yso:p4354</code>. Default ordering is decreasing order by the number of events found.</p>
<h4 id="keyword-text">Keyword text</h4>
<p>To find keywords that contain a specific string, use the query parameter <code>text</code>.</p>
<p>Example:</p>
<pre><code>keyword/?text=lapset
</code></pre>
<p><a href="?text=lapset" title="json">See the result</a></p>
<h4 id="keyword-source">Keyword source</h4>
<p>Will restrict keywords to a specific data source.</p>
<p>Example:</p>
<pre><code>keyword/?data_source=yso
</code></pre>
<p><a href="?data_source=yso" title="json">See the result</a></p>
<h4 id="ordering">Ordering</h4>
<p>Default ordering is decreasing order by the number of events found. You may also order results by <code>name</code>.
<p>Example:</p>
<pre><code>keyword/?sort=name
</code></pre>
<p><a href="?sort=name" title="json">See the result</a></p>
<h4 id="showing-all-keyword">Showing all keywords</h4>
<p>By default, only those keywords which have listed events are
displayed. You may display keywords with zero <code>n_events</code> with the
query parameter <code>show_all_keywords</code>.</p>
operationId: keyword_list
tags:
- filter
parameters:
- $ref: '#/parameters/page_param'
- $ref: '#/parameters/pagesize_param'
- $ref: '#/parameters/include_param'
# FIXME: use case for 6Aika cities
- name: show_all_keywords
in: query
type: boolean
description: 'Show all keywords, including those that are not associated with any events. Otherwise such keywords are hidden. When show_all_keywords is specified, no other filter is applied, **except** "filter" (match for keywords beginning with string)'
- name: data_source
in: query
type: string
description: 'Search for keywords (**note**: NOT events) that come from the specified data source (see data source in keyword definition).'
- name: text
in: query
type: string
description: 'Search for keywords (**note**: NOT events) that contain the given string. This applies even when show_all_keywords is specified.'
- $ref: '#/parameters/keyword_sort_param'
responses:
200:
description: List of keywords
schema:
type: object
properties:
meta:
$ref: '#/definitions/meta_definition'
data:
type: array
items:
$ref: '#/definitions/keyword'
/keyword/{id}/:
get:
summary: Return information for single keyword
operationId: keyword_retrieve
tags:
- filter
responses:
200:
description: Keyword record
schema:
$ref: '#/definitions/keyword'
parameters:
- type: string
description: Same as id in keyword schema
in: path
name: id
required: true
/keyword_set/:
get:
summary: Return as list of keyword_sets for grouping keywords
description: Unlike other endpoints, keyword_sets do not support filtering. It is expected that the full result set will remain small enough.