-
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathapi_main.apib
121 lines (88 loc) · 5.21 KB
/
api_main.apib
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
FORMAT: 1A
HOST: https://master-goggles.org
# Goggles 'core7' API
Backend internal API for the Goggles Engine, core7.
| _Framework_ | _API_ | _App version_ | _DB structure_ | _latest update_ |
| --- | --- | --- | --- | --- |
| `core7` | `v3` | 7-0.7.10 | 2.07.2 | 20240425 |
_Previous legacy versions are deprecated and subseeded by this._
* * *
## API routes naming ("find" vs "search" vs "list")
"`find`" is used as a verb in API routes to discriminate requests that will yield a _single result_.
Conversely, "`search`" and "`list`" are used whenever the request supports multiple results, with the
difference being that "`list`" results are simple or filtered queries, whereas "`search`" implies always
some kind of special back-end strategy (fuzzy matching, neural networks, deep search, whatever the case).
For this reason, sometimes the "`search`" endpoints may result particularly slower when compared to the timing
required by a possibly similar "`list`" fetch. (But this comparison is not always possible.)
One exception to this naming scheme is the "`lookup`" group of endpoints, which is specifically chosen for
just looking up the read-only values of secondary subentities & lookup tables.
Typically, whenever an endpoint path includes the full name of a specific DB entity (as in `meeting_programs`
or `meeting_reservations`), the supported CRUD operations will always include _reading_ data,
most of the times _updating_, some times _creating_ and, in a few cases, even _deleting_.
The supported CRUD operations depend on how critical the entity is deemed to be.
For instance, meeting reservations or meeting entries can be fully managed by this API.
As a rule of thumb, if the entity allows remote creation by end-users, full CRUD support is usually
conceeded and available with some kind of grant.
## Details retrieval requests
Whenever a _dedicated_ endpoint exists for an entity (i.e.: `GET /<entity_name>/<id>`),
retrieving that specific single row with a `GET .../{id}` may yield a more fine-grained structure
as many multiple association rows are condensed and summarized in detail (depending on the depth level).
For ease of usage, most of the associated details nested in each sub-entity are included anyway
even when this yields a bit of redundancy.
(For example, the list of associated events included in a MeetingProgram row detail response will contain inevitably
less associations and details than those obtained by retrieving each specific meeting event or result one by one.)
Also of note, most of these detail retrieval endpoints (`GET /<entity_name>/<id>`) will support an optional `locale`
parameter for translating specific locale-dependent display labels (default locale code is currently `it`).
_Supported locales:_
| Locale code | description |
| --- | --- |
| `it` | **default**, Italian |
| `en` | English |
## Maintenance mode
The app framework supports two different "maintenance" modes to inhibit most HTTP & API requests:
"soft" (or logic) maintenance & "hard" maintenance modes.
During _"soft" maintenenace_, a flag on the database will be set, new JWT sessions will be refused and any incoming API request
will be rejected with a `"Maintenance mode is ON"` error message - unless the
requesting user has admin grants.
Conversely, _"hard" mainentenance_ mode disables the app running on the host with a static site and does not
change the database. API sessions may still be available during "hard" maintenance mode, given that the
API endpoints are also served from a different container.
* * *
<!-- include(blueprint/session.apib) -->
<!-- include(blueprint/admin_grants.apib) -->
<!-- include(blueprint/api_daily_uses.apib) -->
<!-- include(blueprint/badge_payments.apib) -->
<!-- include(blueprint/badges.apib) -->
<!-- include(blueprint/calendars.apib) -->
<!-- include(blueprint/category_types.apib) -->
<!-- include(blueprint/cities.apib) -->
<!-- include(blueprint/federation_types.apib) -->
<!-- include(blueprint/individual_records.apib) -->
<!-- include(blueprint/import_queues.apib) -->
<!-- include(blueprint/issues.apib) -->
<!-- include(blueprint/laps.apib) -->
<!-- include(blueprint/lookup.apib) -->
<!-- include(blueprint/meeting_entries.apib) -->
<!-- include(blueprint/meeting_events.apib) -->
<!-- include(blueprint/meeting_individual_results.apib) -->
<!-- include(blueprint/meeting_programs.apib) -->
<!-- include(blueprint/meeting_relay_results.apib) -->
<!-- include(blueprint/meeting_relay_swimmers.apib) -->
<!-- include(blueprint/meeting_reservations.apib) -->
<!-- include(blueprint/meeting_sessions.apib) -->
<!-- include(blueprint/meetings.apib) -->
<!-- include(blueprint/relay_laps.apib) -->
<!-- include(blueprint/season_types.apib) -->
<!-- include(blueprint/seasons.apib) -->
<!-- include(blueprint/settings.apib) -->
<!-- include(blueprint/standard_timings.apib) -->
<!-- include(blueprint/swimmers.apib) -->
<!-- include(blueprint/swimming_pools.apib) -->
<!-- include(blueprint/team_affiliations.apib) -->
<!-- include(blueprint/team_managers.apib) -->
<!-- include(blueprint/teams.apib) -->
<!-- include(blueprint/tools.apib) -->
<!-- include(blueprint/user_laps.apib) -->
<!-- include(blueprint/user_results.apib) -->
<!-- include(blueprint/user_workshops.apib) -->
<!-- include(blueprint/users.apib) -->