Skip to Content
Last modified by Xwiki VePa on 2024/02/07 07:37
Show last authors
1 {{layout}}
2 {{layout-section ac:type="two_right_sidebar"}}
3 {{layout-cell}}
4 (% style="color: rgb(68,68,68);text-decoration: none;" %)Tässä ohjeessa kerrotaan ohjeet rajapinnan julkaisemiseen HY:n Api gateway alustassa.
5
6 == (% style="letter-spacing: -0.008em;" %)1 API-Gateway alusta(%%) ==
7
8 (% style="letter-spacing: -0.008em;" %)Mikäli haluat tietää yleiskuvauksen valitusta API-gateway alustasta, niin käy lukemassa ensimmäinen ohjesivu: [[doc:SO.Sovelluskehittäjän ohjeet.Integraatiot.API-Gateway.1 - API-Gateway (Gravitee) yleiskuvaus.WebHome]].
9
10 == 2 API-hallinta ==
11
12 Helsingin yliopisto on laatinut API-hallintamallin, jossa linjataan, mitä API:n julkaisussa on syytä huomioida ja millä tavoin API-hallintaa toteutetaan. Mikäli et ole vielä tutustunut API-hallintamalliin, on voi siihen tutustua siihen ennen API:n julkaisua.
13
14 [[doc:SO.Sovelluskehittäjän ohjeet.Integraatiot.API-Gateway.1 - API-Gateway (Gravitee) yleiskuvaus.API-hallintamalli.WebHome]]
15
16 == 3 Checklist / tarkistuslista ennen rajapinnan julkaisua ==
17
18 Ennen julkaisua on syytä tarkistaa seuraavat kohdat ennen julkaisun tekemistä.
19
20 (% class="relative-table wrapped" %)
21 |(% class="highlight-blue" style="text-align: left;" colspan="5" data-highlight-colour="blue" %)(% class="highlight-blue" style="text-align: left;" colspan="5" data-highlight-colour="blue" %)
22 (((
23 ==== 1 Ohjeiden lukeminen ja pääsy API-gateway alustaan ====
24 )))
25 |(% class="highlight-blue" style="text-align: left;" colspan="2" data-highlight-colour="blue" %)(% class="highlight-blue" style="text-align: left;" colspan="2" data-highlight-colour="blue" %)
26 (((
27 **Mikä**
28 )))|(% class="highlight-blue" style="text-align: left;" colspan="1" data-highlight-colour="blue" %)(% class="highlight-blue" style="text-align: left;" colspan="1" data-highlight-colour="blue" %)
29 (((
30 **Tarkennus**
31 )))|(% class="highlight-green" style="text-align: left;" colspan="1" data-highlight-colour="green" %)(% class="highlight-green" style="text-align: left;" colspan="1" data-highlight-colour="green" %)
32 (((
33 **Tarkistettu  (pvm)**
34 )))|(% class="highlight-green" style="text-align: left;" colspan="1" data-highlight-colour="green" %)(% class="highlight-green" style="text-align: left;" colspan="1" data-highlight-colour="green" %)
35 (((
36 **Huomioita**
37 )))
38 |(% style="text-align: left;" %)(% style="text-align: left;" %)
39 (((
40 1a
41 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
42 (((
43 API-gateway alustan yleiskuvauksen lukeminen (suositus)
44 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
45 (((
46 \\
47 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
48 (((
49 \\
50 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
51 (((
52 \\
53 )))
54 |(% style="text-align: left;" %)(% style="text-align: left;" %)
55 (((
56 1b
57 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
58 (((
59 API-rajapinnan julkaisuohjeen lukeminen (suositus)
60 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
61 (((
62 \\
63 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
64 (((
65 \\
66 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
67 (((
68 \\
69 )))
70 |(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
71 (((
72 1c
73 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
74 (((
75 Tämä checklist täytettynä
76 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
77 (((
78 \\
79 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
80 (((
81 \\
82 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
83 (((
84 \\
85 )))
86 |(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
87 (((
88 1d
89 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
90 (((
91 Käyttöoikeuden hakeminen
92 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
93 (((
94 \\
95 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
96 (((
97 \\
98 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
99 (((
100 \\
101 )))
102 |(% class="highlight-blue" style="text-align: left;" colspan="5" data-highlight-colour="blue" %)(% class="highlight-blue" style="text-align: left;" colspan="5" data-highlight-colour="blue" %)
103 (((
104 ==== 2 Vaatimukset rajapintaan liittyen ====
105 )))
106 |(% style="text-align: left;" %)(% style="text-align: left;" %)
107 (((
108 2a
109 )))|(% style="text-align: left;" %)(% style="text-align: left;" %)
110 (((
111 Rajapinnalla on omistaja
112 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
113 (((
114 (% style="color: rgb(0,0,0);" %)Yksittäisten API:n julkaisuun liittyvät toimet kuuluvat API:n omistajalle/kehittäjälle. API:n omistaja määrittelee myös sen, kuka rajapintaa saa käyttää ja millaisilla ehdoilla. Rajapintojen julkaisu ja tuen antaminen yksittäisen rajapinnan osalta kuuluu API:n omistajalle/kehittäjälle.
115 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
116 (((
117 \\
118 )))|(% style="text-align: left;" colspan="1" %)(% style="text-align: left;" colspan="1" %)
119 (((
120 \\
121 )))
122 |(% colspan="1" %)(% colspan="1" %)
123 (((
124 2b
125 )))|(% colspan="1" %)(% colspan="1" %)
126 (((
127 Rajapinnan dokumentaatio (swagger) on tuotettu vaaditulla tarkkuustasolla.
128 )))|(% colspan="1" %)(% colspan="1" %)
129 (((
130 Rajapinnan kuvaukselta edellytetään OpenAPI (Swagger) -standardin mukainen kuvaus, joka sisältää:
131
132 * palvelun nimi ja kuvaus (mitä palvelu tekee)
133 * palvelun teknisen ylläpidon yhteysosoite
134 * julkaistava palvelun osoite gatewayllä. Ensimmäisessä swagger-importissa vaaditaan yksilöivä basePath tai server urlin path, johon api oletuksena julkaistaan. Esimerkiksi basepath: /organisation tai url: [[https:~~/~~/api.helsinki.fi/organisation>>url:https://api.helsinki.fi/organisation||shape="rect"]]
135 * JOS julkaistava palvelu sisältää henkilötietoa, julkaisu tulee tehdä basePath /securen alle esimerkiksi /secure/persondata
136 * rajapinnan kutsuosoitteet kuten /organisation/financial sekä niiden tarkat kuvaukset
137 * kutsuesimerkit tarkalla tasolla: Onko GET/POST/muu, json vai muu, mahdolliset annettavat lisäparametrit, pakolliset kentät
138 * sanomamuodot: application/json, text/xml, palautettavan tai lähetettävän objektin tarkka kuvaus kenttien tyyppeineen sekä rajoitteineen(maksimi pituus)
139 * tunnistautuminen: vaaditaanko esimerkiksi api-avain joillekin metodeille/koko APIlle. Oletuksena vaaditaan vähintään Api-avain jokaiselle rajapinnalle. On tärkeää muistaa nämä määritykset swagger-dokumentaatiossa.
140 * virheilmoituksien kuvaukset: esimerkiksi 404 = ei löydy
141 * lisenssiehdot, jos on
142 )))|(% colspan="1" %)(% colspan="1" %)
143 (((
144 \\
145 )))|(% colspan="1" %)(% colspan="1" %)
146 (((
147 \\
148 )))
149
150 \\
151
152 == 4 Rajapinnan avaaminen API-gateway-alustalle ==
153
154 Taustapalvelu, joka julkaisee rajapinnan tulee avata tietoliikenteellisesti API-gateway alustalle. Api-gateway nodet sijaitsevat seuraavissa osoitteissa
155
156 (% class="relative-table wrapped" style="width: 58.1994%;" %)
157 |=(% colspan="1" %)(% colspan="1" %)
158 (((
159 Node
160 )))|=(((
161 Tuotantoympäristön node
162 )))|=(% colspan="1" %)(% colspan="1" %)
163 (((
164 IP-osoite
165 )))
166 |(% colspan="1" %)(% colspan="1" %)
167 (((
168 1
169 )))|(((
170 api-prod-gw-1-19.it.helsinki.fi
171 )))|(% colspan="1" %)(% colspan="1" %)
172 (((
173 128.214.224.137
174 )))
175 |(% colspan="1" %)(% colspan="1" %)
176 (((
177 2
178 )))|(((
179 api-prod-gw-2-19.it.helsinki.fi
180 )))|(% colspan="1" %)(% colspan="1" %)
181 (((
182 128.214.224.226
183 )))
184 |(% colspan="1" %)(% colspan="1" %)
185 (((
186 \\
187 )))|(((
188 \\
189 )))|(% colspan="1" %)(% colspan="1" %)
190 (((
191 \\
192 )))
193 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
194 (((
195 **Node**
196 )))|(% class="highlight-grey" title="Taustaväri: Harmaa" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" title="Taustaväri: Harmaa" colspan="1" data-highlight-colour="grey" %)
197 (((
198 **Testiympäristön node**
199 )))|(% class="highlight-grey" title="Taustaväri: Harmaa" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" title="Taustaväri: Harmaa" colspan="1" data-highlight-colour="grey" %)
200 (((
201 **IP-osoite**
202 )))
203 |(% colspan="1" %)(% colspan="1" %)
204 (((
205 1
206 )))|(% colspan="1" %)(% colspan="1" %)
207 (((
208 api-test-1-19.it.helsinki.fi
209 )))|(% colspan="1" %)(% colspan="1" %)
210 (((
211 128.214.224.232
212 )))
213
214 \\
215
216 == 5 Rajapinnan nimeäminen ==
217
218 Rajapinnan nimeämiseen on syytä kiinnittää huomiota, koska huonosti nimetty rajapinta aiheuttaa helposti sekaannusta kutsujissa
219
220 \\
221
222 (% style="list-style-type: square;" %)
223 * Rajapinnan nimen ensimmäinen osa voi olla lähettävän järjestelmän nimi tai muu lähettäjää kuvaava substantiivi ja seuraava osa kuvaa lähetettävää tietoa.\\
224 (% style="list-style-type: square;" %)
225 ** **esim. /message-center/notification(s) **
226 * Kuvattu tieto on yksikössä, jos rajapinta palauttaa yhden tiedon ja monikossa jos palautettavia tietueita on useampia
227 * Rajapinnan nimen tulee olla **kuvaava ja selkeä,** niin että kutsuva taho ymmärtää mitä rajapintaa on kutsumassa. Rajapinnan nimi on miellään oikea sana
228 * Rajapinta tulee mielellään olla englanniksi tai samalla kielellä, kun palautettava tieto on (jos rajapinta palauttaa tiedon vain suomeksi voi rajapinnan nimikin olla suomeksi)
229 * Käytä "/"-merkkiä erottaaksesi rakenteisen datan alaosat toisistaan
230 (% style="list-style-type: square;" %)
231 ** esim: /message-center/notifications/{id}/recipient
232 * Käytä "-"-merkkiä helpottaaksesi pitkien nimien luettavuutta
233 (% style="list-style-type: square;" %)
234 ** **esim: message-center-test**
235 * /secure/ polku on turvattu alue ja siellä julkaistut apit vaativat tls client sertifikaatin
236 (% style="list-style-type: square;" %)
237 ** **esim. /secure/message-center/notifications**
238
239 \\
240
241 == 6 Polun määrittely ==
242
243 \\
244
245 API:n polku määritellään API-gatewaylle ja se reititään kohde palvelimella oikeaan polkuun. Konfigurointeja tehdään seuraaviin kohtiin:
246
247 \\
248
249 Swagger-dokumentti
250
251 (% style="list-style-type: square;" %)
252 * Servers url parametri Esim. '[[https:~~/~~/api-test.it.helsinki.fi/mece>>url:https://api-test.it.helsinki.fi/mece||shape="rect"]]
253 * Tämän lisäksi swagger-dokumentissä määritellään polut
254
255 Configuration -välilehti
256
257 * Base-url esim: [[https:~~/~~/api-test.it.helsinki.fi/message-center>>url:https://api-test.it.helsinki.fi/message-center||shape="rect"]]
258 * Tämän lisäksi Swagger servers URL are based on the entrypoints
259
260 Endpoints konfiguration
261
262 * Mihin liikenne ohjataan
263
264 Entrypoint
265
266 * Esim. message-center (mikä osoite näytetään ulospäin)
267
268 \\
269
270 \\
271
272 \\
273
274 \\
275 {{/layout-cell}}
276
277 {{layout-cell}}
278 (% class="auto-cursor-target" %)
279 Parasta ennen: 09.06.2020
280
281 {{info title="Vaikeustaso"}}
282 Tekninen:
283
284 Hallinnollinen:
285
286 Koordinointi:
287
288 Kalenteriaika:
289 {{/info}}
290
291 (% class="auto-cursor-target" %)
292 \\
293
294 (% class="wrapped" %)
295 |=(% style="text-align: center;" colspan="2" %)(% style="text-align: center;" colspan="2" %)
296 (((
297 Vastuunjako
298 )))
299 |=(((
300 Ohjeistus
301 )))|(((
302 [[tike-ohjelmistotuotanto@helsinki.fi>>mailto:tike-ohjelmistotuotanto@helsinki.fi||shape="rect"]]
303 )))
304 |=(((
305 Tekninen alusta
306 )))|(((
307 tike-integraatiopalvelu@helsinki.fi
308 )))
309
310 (% class="auto-cursor-target" %)
311 \\
312
313 {{info title="Yhteystietoja"}}
314 [[tike-ohjelmistotuotanto@helsinki.fi>>mailto:tike-ohjelmistotuotanto@helsinki.fi||shape="rect"]]
315 {{/info}}
316
317 (% class="auto-cursor-target" %)
318 \\
319
320 \\
321
322 (% class="auto-cursor-target" %)
323
324
325 {{toc/}}
326
327 \\
328
329 (% class="auto-cursor-target" %)
330 \\
331 {{/layout-cell}}
332 {{/layout-section}}
333 {{/layout}}