POST-meetod: toote lisamine
Saad teada, kuidas administraator lisab veebipoe kataloogi uue toote. Vaatame, kuidas toimib POST-päring, mida sisaldab päringu keha, mida tähendab edukat loomist näitav olekukood 201 ning kuidas uus toode andmebaasi salvestatakse.
Tootest
Tere! Sa juba tead, kuidas ostja BB Foodi kataloogi laadib. Nüüd vaatame teist poolt: poel on admin-paneel, kus administraator lisab uusi tooteid. Siin klient enam ainult ei loe andmeid, vaid saadab neid serverisse.
Huvitav! Aga kuidas see töötab?
Seda seletab kõige paremini Kadri — Kadri ootab sind juba nõupidamisruumis. Täna võtame ainult positiivse stsenaariumi: kõik läheb nii, nagu peab.
Tere! Kas mäletad GET-meetodit? See saab andmeid ja ei muuda midagi. Administraatoril on aga vaja midagi muud: luua kataloogi uus toode. Selleks on HTTP-s POST-meetod.
Tere, Kadri! Aga mille poolest POST GET-ist erineb?
GET tähendab „saa“ ja POST tähendab „loo“. Klient saadab POST-päringu koos uue toote andmetega. Nii see välja näeb:
Päring
POST /api/v1/products
{
"name": "Kodujuust, 200 g",
"price": 1.89
}- meetod — mida teha.
POSTtähendab „loo“ - aadress — millega.
/api/v1/productson sama tootenimekiri mis GET-is - päringu keha (request body) — andmed, mida klient serverile saadab. Siin on selleks uue toote nimi ja hind JSON-vormingus. Päringus pole
id-d tahtlikult: klient seda ei saada, uuele tootele annab numbri serveri poolel andmebaas
Ja mida server sellisele päringule vastab?
Server salvestab toote andmebaasi ja saadab vastuse. Kood 201 Created tähendab „loodud“ — see on edukas vastus just POST-i jaoks. Vastuse kehas tagastab server loodud toote. Pane tähele id: klient seda ei saatnud, numbri annab andmebaas.
Vastus
201 Created
{
"id": 8,
"name": "Kodujuust, 200 g",
"price": 1.89
}- olekukood — kuidas läks.
201 Createdtähendab „loodud“ - vastuse keha (response body) — loodud toode, nüüd koos
id-ga
Märkus. HTTP standardi järgi vastatakse loomisele koodiga 201 Created. Praktikas võib aga näha ka 200 OK: see sõltub sellest, kuidas server on tehtud. Kui meeskonnas on kokku lepitud, et loomisel tagastatakse 200, pole see viga. Lihtsalt pea meeles, et nii juhtub, ja vaata API dokumentatsiooni.
Kontrollime, kas on selge. Administraator täitis vormi ja vajutas „Lisa toode“. Millise meetodi klient saadab?
Vaatame seda praktikas!
Siin on BB Foodi admin-paneel. Vormi on juba pandud näidistoode, mida saad muuta. Vajuta „Lisa toode“ ja jälgi päringu teed: klient → server → andmebaas → server → klient.
Testitav rakendus
Stsenaarium. Positiivne: administraator lisab toote
Sisesta nimi ja hind — number, mis on suurem kui null.
Server ootab päringuid. Vajuta „Lisa toode“, et klient saadaks päringu POST /api/v1/products.
Animatsioon on aeglustatud: tegelikult võtab kogu teekond mõnikümmend millisekundit.
| id | name | price |
|---|---|---|
| 1 | Banaanid, 1 kg | 1.49 |
| 2 | Kirsstomatid, 250 g | 2.29 |
| 3 | Piim 2,5%, 1 l | 1.19 |
| 4 | Gouda juust, 200 g | 2.99 |
| 5 | Rukkileib | 1.79 |
| 6 | Apelsinimahl, 1 l | 2.49 |
| 7 | Soolaheeringas, 300 g | 3.29 |
Valmis! Toode on andmebaasi salvestatud ja server tagastas 201 Created ning loodud toote koos id-ga. Vaata tabelit: sinna ilmus uus rida. Seega POST muutis erinevalt GET-ist serveris andmeid.
Aga mis juhtub, kui administraator vajutab „Lisa toode“ uuesti samade andmetega?
Aga mida ma siin kontrollima peaksin?
Kontrolli kolme asja. Esiteks: vastuse kood on 201 Created (või see, milles meeskond kokku leppis). Teiseks: vastuses on id, nimi ja hind on samad, mis administraator sisestas. Kolmandaks: toode ilmus andmebaasi tabelisse, seega näeb ostja seda kataloogis, kui klient küsib tootenimekirja päringuga GET /api/v1/products. POST ise seda nimekirja ei näita — selleks on vaja eraldi GET-päringut. See ongi POST-i positiivne stsenaarium.
Lühiviide
POST-meetod
POST /api/v1/products tähendab „loo“. Klient saadab andmed päringu kehas ja server salvestab need andmebaasi. Erinevalt GET-ist muudab POST serveris andmeid.
Päringu keha
Andmed, mida klient serverile saadab, enamasti JSON-vormingus. Uue toote puhul on need nimi ja hind.
Kood 201 Created
Edukas vastus loomisele. Vastuse kehas tagastab server tavaliselt loodud objekti, juba identifikaatoriga.
Identifikaator (id)
Klient seda ei saada: uue kirje unikaalse numbri annab andmebaas.
POST-i kordamine
Iga POST loob uue kirje, seega annab kordus samade andmetega duplikaadi. GET-il sellist probleemi pole: see ainult loeb andmeid.
Mida testija kontrollib
Vastuse kood on 201 (või see, milles meeskond kokku leppis). Vastuses on id ning nimi ja hind on samad, mis sisestati. Andmebaasi ilmus uus rida ja ostja näeb toodet kataloogis.