Tutvus Postmaniga: kes veel võib olla klient
Saad teada, mis on API ja endpoint ning miks ei ole klient ainult brauser. Tutvud Postmaniga kui testija töövahendiga, õpid eristama path- ja query-parameetreid ning tundma Postmani peamisi tööalasid.
Tootest
Tere! On uus ülesanne. Meeskond teeb BB Foodi kataloogi ümber: uue API-ga server on valmis, kuid kataloogilehte frontend-arendajad alles teevad. API on vaja kohe ära kontrollida.
Aga kuidas seda ilma leheta kontrollida? Brauseril pole ju midagi avada.
Hea küsimus! Päringuid saab saata mitte ainult brauserist. Kadri näitab tööriista, mida testijad iga päev kasutavad, — Postmani.
Tere! Enne kui Postmani avame, selgitame välja sõnad, mida hakkad nüüd iga päev kuulma.
Alex ütles, et API on valmis. Mis on API?
API (Application Programming Interface, rakendusliides) on viis, kuidas programmid omavahel suhtlevad. Server teatab ette: „Selliseid päringuid ma mõistan ja nii neile vastan.“ Klient saab kasutada ainult seda: serveri sisse ja andmebaasi ta ei vaata.
Kujuta ette letiga toidupoodi. Ostja ei lähe leti taha ega lattu: ta vaatab hinnakirja ja küsib vajalikku kaupa, müüja võtab tellimuse vastu ja toob kauba laost.
- API on lett koos hinnakirjagaLoetelu sellest, mida saab küsida, ja reeglid, kuidas küsida.
- API on serveri osaLett pole eraldi hoone, vaid poe osa. Samamoodi pole API eraldi programm, vaid serveri enda osa: tema „sissepääs“, mille kaudu server päringuid vastu võtab.
API testija töö on saata serverile selle loetelu päringuid ja kontrollida vastuseid. Ja mitte ainult korrektseid päringuid, vaid ka vigaseid: tühjade väljade, valede andmete või autoriseerimiseta.
Kontrollime. Mis on API?
Arendajad räägivad kogu aeg ka „endpoint“. Mis see on?
Endpoint („lõpp-punkt“) on selle hinnakirja üks konkreetne rida: meetod koos teega, mille kaudu saab serveri poole pöörduda. Näiteks GET /api/v1/products — „saa toodete nimekiri“.
Päringu täisaadress koosneb serveri baasaadressist (base URL) ja teest. Baasaadress on kogu API-l ühine, meetodid ja teed on endpointidel aga erinevad.
GETmeetodhttps://bb-food.eebase URL/api/v1/productsteeendpoint=GET+/api/v1/products
Kõik endpointid koos kirjeldustega on tavaliselt koondatud API dokumentatsiooni, sageli Swaggerisse. Swagger genereeritakse tavaliselt automaatselt backendi koodist — programmist, mis töötab serveris. Seepärast on selles näha, mida server päriselt oskab. Sellest testija alustabki. Selline on meie kataloogi „hinnakiri“:
Sama tee eri meetoditega on erinevad endpointid: GET /api/v1/products loeb nimekirja, POST /api/v1/products aga lisab toote. {id} asemele pannakse toote number — selle juurde tuleme veidi hiljem tagasi.
Mitu erinevat endpointi siin on?
GET /api/v1/products
POST /api/v1/products
GET /api/v1/products/{id}Nüüd klientidest. Sarjas „Klient-server“ saatis API-le päringuid alati brauser. Seepärast on lihtne arvata, et klient ongi brauser. Aga see pole nii.
Kes veel võib olla klient?
Klient on iga programm, mis saadab serverile päringu. Serveril on ükskõik, kes tema poole pöördus: ta näeb ainult päringut ennast — meetodit, aadressi, päiseid ja keha — ning vastab sellele.
Ostja avab kataloogi brauseris — klient on brauser. Mobiilirakenduses — klient on rakendus.
Kontrollime. Ostja brauser, poe mobiilirakendus ja testija Postman saadavad päringuid meie serverisse. Kes neist on klient?
Mille poolest erineb vastus Postmanis sellest, mida brauseris näha on?
Serveri vastus ise on täpselt sama. Erinevus on selles, kuidas klient seda näitab.
Brauser võtab JSON-i ja joonistab sellest lehe: tootekaardid, hinnad, nupud. Postman ei joonista midagi. Ta näitab vastust nii, nagu see on: olekukood, aeg, suurus ja JSON ise.
[
{"id": 1, "name": "Banaanid, 1 kg", "price": 1.49},
{"id": 5, "name": "Rukkileib", "price": 1.79}
]Testijal on vaja mõlemat: Postman näitab, mida server vastas, ja brauser, mida kasutaja sellest nägi.
Brauser ja Postman saatsid serverile ühesugused päringud GET /api/v1/products. Mille poolest vastused erinevad?
Aga milleks peaks testija saatma päringuid brauserist mööda?
Põhjusi on mitu:
- Liidest pole vaja oodata — API-t saab kontrollida juba enne, kui leht on valmis. Täpselt meie juhtum.
- Leida, kus viga on — kui Postmanis on vastus õige, aga lehel vale, on viga kliendis. Kui vastus on vale juba Postmanis, on viga serveris.
- Saata seda, mida vorm ei luba — tühi nimi, hind tähtedega, võõras id, päring ilma tokenita. Server peab ennast ise kaitsma, mitte vormile lootma.
- Töötada kiiremini — ühe toimingu kontrollimiseks ei pea iga kord kogu lehte läbi käima.
Ostja kurdab: veebilehe kataloogis pole rukkileiba. Saadad Postmanist GET /api/v1/products ja leib on vastuses olemas. Kust viga otsida?
Adminpaneeli vorm ei lase hinda tähtedega sisestada. Kas server ei salvesta siis kindlasti hinda „abc“?
Kuule, aadressides olen näinud nii /api/v1/products/5 kui ka ?sort=price. Kas see on üks ja sama?
Hea küsimus — süveneme veidi päringu aadressi. Aadressis saab andmeid edastada kahel viisil.
Path-parameeter on tee enda osa. Aadressis /api/v1/products/5 ütleb number 5, millise toote kallal just töötame. Oleme seda juba näinud PATCH-i, PUT-i ja DELETE-i juures. Ilma selleta tähendab aadress muud: /api/v1/products on kogu nimekiri.
Query-parameetrid kirjutatakse pärast ?-märki: „võti=väärtus“ paarid, mis on eraldatud &-märgiga. Need ei vali ressurssi, vaid täpsustavad päringut: filtreerida, sorteerida, piirata kogust. /api/v1/products?category=bread&sort=price tähendab „anna leivakategooria tooted hinna järgi sorteerituna“. Query-parameetrite järjekord pole oluline ja sageli võib need üldse ära jätta.
https://bb-food.eeserveri aadress/api/v1/products/tee5path-parameeterhttps://bb-food.eeserveri aadress/api/v1/productstee?category=bread&sort=pricequery-parameetridVihje: path vastab küsimusele „milline täpselt?“ — konkreetne toode, tellimus, kasutaja. Query vastab küsimusele „millised ja kuidas?“ — filter, sorteerimine, lehekülg.
On vaja saada üks toode — id-ga 7. Milline aadress on õige?
Ostja valis kataloogis „ainult leib, odavamad enne“. Kuidas see aadressis tõenäoliselt välja näeb?
Selge! Aga mida Postman oskab?
Vaatame tema akent. Vajuta mis tahes osale — räägin, mis seal on. Märgiga „edaspidi“ on tähistatud see, mida käsitleme põhjalikult järgmistes plokkides.
Vaadatud: 0/12
Vali akna osa ülal.
Päringurida
Vasakul valid meetodi: GET, POST, PUT, PATCH või DELETE. Paremal kirjutad aadressi. Nupp Send saadab päringu — just sel hetkel saabki Postmanist klient.
Params
Tabel Query Params: kirjuta sort = price ja Postman lisab ise aadressi lõppu ?sort=price. Kui aga kirjutad aadressi /api/v1/products/:id, ilmub allapoole tabel Path Variables — seal määrad path-parameetri, näiteks id = 5.
Authorization
Siin märgitakse, kes päringu saadab: token (Bearer Token), kasutajanimi ja parool (Basic Auth) või API võti. Eemalda token ja kontrolli, et server vastab 401.
Headers
Päised on päringu teenindusinfo. Näiteks Content-Type: application/json ütleb serverile, et kehas on JSON. Paljud päised lisab Postman ise.
Body
Päringu keha POST-i, PUT-i ja PATCH-i jaoks. Enamasti on see JSON (raw → JSON), vahel failidega vorm (form-data). Siit saab saata mida tahes — isegi seda, mida veebilehe vorm läbi ei lase.
Scriptsedaspidi
Väikesed JavaScripti programmid, mis käivituvad enne või pärast päringut. Näiteks kontrollivad nad ise, et vastuse kood on 200 ja vastuses on vajalik väli. Need on automatiseerimise esimesed sammud.
Olek, aeg, suurus
Vastuse kood (200 OK), mitme millisekundiga server vastas ja kui suur vastus on. Liiga aeglane vastus on samuti põhjus veateateks.
Vastuse keha
See, mille server saatis. Pretty — taanete ja esiletõstuga, Raw — nii, nagu tuli, Preview — nii, nagu brauser näitaks. Kõrval on vahelehed vastuse päiste ja küpsistega.
Collections
Salvestatud päringud kaustadesse jaotatuna: näiteks „Kataloog“, „Ostukorv“, „Adminpaneel“. Kollektsiooni saab meeskonnaga jagada, et kõik kontrolliksid sama asja.
Environments
Keskkonnad ja muutujad. Aadressi asemel kirjutad {{baseUrl}} ja selle väärtus sõltub keskkonnast: testserver või toodangu server. Vahetasid keskkonda — ja kõik päringud lähevad teise serverisse.
History
Kõik päringud, mida oled saatnud, ka salvestamata. Eilse kontrolli saab ühe klõpsuga korrata.
Import, Runner, Mockedaspidi
Import laadib valmis päringud API kirjeldusest (OpenAPI, Swagger) või cURL-käsust. Runner käivitab kogu kollektsiooni korraga. Mock-server vastab asendusvastustega, kuni päris API-t veel pole.
Vaatasin kõik üle, kontrollime!
Sul on vaja lisada toode POST-iga. Kuhu Postmanis uue toote JSON kirjutada?
Tuleb kontrollida, et ilma sisselogimiseta toodet lisada ei saa. Kus Postmanis token eemaldada?
Eile kontrollisid päringut, aga unustasid selle salvestada. Kust selle leiad?
Samu päringuid tuleb saata vahel testserverisse, vahel toodangu serverisse. Kuidas vältida aadressi ümberkirjutamist igas päringus?
Suurepärane! Nüüd tead, et Postman on samasugune klient nagu brauser, ja mis tema aknas kus asub. Edasi saadame selles plokis päringuid ise, alustades GET-iga.
Lühiviide
API
Reeglid, mille järgi programmid suhtlevad: milliseid päringuid server mõistab ja mida ta neile vastab. Nagu poelett koos hinnakirjaga: ostja küsib kaupa hinnakirja järgi ega lähe lattu, klient pöördub API poole ega lähe andmebaasi.
Endpoint
API üks konkreetne punkt: meetod koos teega, näiteks GET /api/v1/products. Täisaadress on baasaadress (base URL) pluss tee. Sama tee eri meetoditega on erinevad endpointid. Kõik need on kirjeldatud API dokumentatsioonis, sageli Swaggeris, mis genereeritakse tavaliselt automaatselt backendi koodist.
Kes võib olla klient
Klient on iga programm, mis saadab serverile päringu: brauser, mobiilirakendus või Postman. Server näeb ainult päringut ja vastab ühesugustele päringutele ühtemoodi.
Postman
Programm API-le päringute käsitsi saatmiseks. Näitab vastust nii, nagu see on: olekukood, aeg, suurus, päised ja keha. Brauser seevastu joonistab vastusest lehe.
Milleks testija liidesest mööda läheb
Et kontrollida API-t enne, kui leht on valmis; mõista, kus viga on — kliendis või serveris; saata andmeid, mida vorm läbi ei lase; korrata kontrolle kiiremini.
Path- ja query-parameetrid
Path-parameeter on tee osa ja valib konkreetse ressursi: /api/v1/products/5. Query-parameetrid tulevad pärast ?-märki võti=väärtus paaridena, eraldatud &-ga, ja täpsustavad päringut: /api/v1/products?category=bread&sort=price.
Postmani aken
Päringurida (meetod, aadress, Send), vahelehed Params, Authorization, Headers, Body ja Scripts ning vastuse paneel. Vasakul on kollektsioonid, keskkonnad ja ajalugu.
Kollektsioonid ja keskkonnad
Kollektsioon on kaustadesse salvestatud päringud, mida saab meeskonnaga jagada. Keskkond hoiab muutujaid, näiteks {{baseUrl}}: vahetasid keskkonda — päringud läksid teise serverisse.