käytännön oppaat

Dokumentoi ja testaa API sen käyttötapauksista

Hyödyllinen API antaa toisen tiimin ymmärtää, mitä se voi pyytää ja mitä se saa. Sen sopimuksen tulee olla testattava, versioitu ja käyttöpalvelun mukainen.

Katso menetelmä

Kuvitus — Dokumentoi ja testaa API sen käyttötapauksista
Tekoälyllä luotu kuvitus

Valitse Tehtävät ennen osoitteita

JavaScript pyöristää luvun 9007199254740993; merkkijono säilyttää numerot.
Kuvitus · JSON.parse-esimerkki: Number pyöristää tunnuksen, String säilyttää numerot. Sovi tekstiesitys ennen muunnosta.

Listaa käyttökohteita, kuten tuotteen löytäminen, saatavuuden lukeminen, tietueen päivittäminen tai käsittelyn seuranta. Määritä valtuutetut ihmiset ja järjestelmät kullekin toiminnolle. Julkisella READ API:lla ja hallinnollisella API:lla on erilaiset pääsyvaatimukset.

Valmistele pyyntö- ja vastausesimerkki jokaisesta olennaisesta tehtävästä käyttämällä synteettisiä arvoja ja selitettyjä kenttiä. Erottele vakaat tunnisteet, tarrat, yksiköt ja päivämäärät. Määritä puuttuvat tiedot sen sijaan, että korvaat tuntemattomilla tiedoilla uskottavia arvoja.

Määritä suuret tunnisteet JSON-sopimuksessa. JavaScriptin binary64-Number säilyttää kokonaisluvut välillä −9007199254740991 ja 9007199254740991 RFC 8259:n tarkan yhteentoimivuusalueen sisällä. 9007199254740992 on esitettävissä mutta ei turvallinen kokonaisluku: viereinen tunnus 9007199254740993 pyöristyy arvoon 9007199254740992 tavallisessa JavaScriptin JSON-purussa.

JSON-merkkijonona sama tunniste säilyttää numerot. Sovi tyyppi tuottajan, skeeman ja kuluttajan kesken; pyöristyneen Number-arvon tekstitys ei palauta alkuperäistä. Muut kirjastot voivat säilyttää enemmän tarkkuutta: testaa tuetut asiakkaat. Kelvollinen JSON ei takaa arvojen säilymistä eikä tyyppi saa vaihtua huomaamatta.

Vieritä taulukkoa vaakasuunnassa nähdäksesi kaikki sarakkeet. Siirrä näppäimistöllä kohdistus taulukkoon ja käytä nuolinäppäimiä.

JavaScriptin JSON-purku: tarkkuus ja tyyppi
Esimerkin JSON-tunnusNäytetty JavaScript-arvoTulkinta
90071992547409919007199254740991Turvallinen kokonaisluku esimerkissä
90071992547409929007199254740992Tarkka, mutta turvallisen alueen ulkopuolella
90071992547409939007199254740992Pyöristynyt: alkuperäinen viimeinen numero kadonnut
"9007199254740993""9007199254740993"Tarkka merkkijono; sovittu tekstityyppi

kuvaile selkeää sopimusta

OpenAPI tarjoaa kielestä riippumattoman kuvausmuodon HTTP-sovellusliittymille, joka kattaa toiminnot, parametrit, vastaukset ja mallit. Valitse työkalujesi tukema versio ja säilytä asiakirja projektin kanssa; Uusin versio ei automaattisesti sovi jokaiseen työkaluketjuun.

Dokumentin käyttörajoitukset, sivutus, suodattimet, tilaukset, virheet ja tyhjät vastaukset. Älä pidä CORS:ää todisteena valtuutuksesta. Tarkista toiminta ja objektitason pääsynhallinta teknisen tiimin kanssa.

Kuvaa kuvitteellisen yhteydenottoja käsittelevän API:n neljä vastausta erikseen. Tässä sopimuksessa 201 palauttaa luodun resurssin Location-otsakkeineen, ja 202 antaa seurantaviitteen, koska työ ei ole valmis. Älä tulkitse jokaista 2xx-vastausta viestiksi ”toiminto valmis”. Asiakkaan on luettava tila, otsakkeet ja kyseiselle toiminnolle määritelty malli.

204-vastauksessa ei ole JSON-muodossa purettavaa sisältöä. Esimerkissä syntaksiltaan oikea mutta liiketoimintasääntöä rikkova ohje saa 422-vastauksen ja rakenteisen ongelman muodossa application/problem+json. Jos status-jäsen annetaan, tuottajan on sovitettava se todelliseen HTTP-tilaan; käännetty detail-teksti ei saa olla ohjelman päätösavain. Dokumentoi vakaat ongelmatunnisteet ja odotettu korjaus.

Vieritä taulukkoa vaakasuunnassa nähdäksesi kaikki sarakkeet. Siirrä näppäimistöllä kohdistus taulukkoon ja käytä nuolinäppäimiä.

Kuvitteellisen API:n neljä vastausta ja niiden vaikutukset asiakkaaseen
Suunniteltu vastausTodennettu asiaKuluttajan tarkistus
201 CreatedResurssi luotuTarkista sopimuksen vaatima Location ja luotu tunniste
202 AcceptedKäsittely hyväksytty, ei valmisSäilytä seurantaviite ja odota lopputulosta
204 No ContentToiminto onnistui ilman vastaussisältöäÄlä pura tyhjää sisältöä JSON-muotona
422 Unprocessable ContentOhje ymmärretty mutta ei käsiteltävissä säännön mukaanLue rakenteinen ongelma ja tarjoa sopiva korjaus
  • RFC 9110 : HTTP Semantics

    RFC 9110, luettu 22. lokakuuta 2026: tilojen merkitys. Vastaukset ja pakolliset kentät määrittävät kuvitteellisen sopimuksen.

  • RFC 9457 : Problem Details

    RFC 9457, luettu 22. lokakuuta 2026: ongelmamuoto ja status-jäsenen rooli.

Estä muokkausta korvaamasta toisen toimittajan muutoksia

  1. Kaksi r7-lukua
  2. Ensimmäinen kirjoitus: r8
  3. Vanha kirjoitus: 412
  4. Vertaa ennen jatkamista

Kuvitteellinen tilanne: kaksi toimittajaa avaa tietueen DEMO-17 vahvalla ETag-arvolla "r7". Ensimmäinen tallentaa korjauksen, jolloin nykyiseksi esitykseksi tulee "r8". Toinen työskentelee yhä version "r7" pohjalta. Ehdollinen kirjoitus voi havaita eron ennen julkaistun version korvaamista.

Tätä sopimusta tukevassa API:ssa asiakas lähettää If-Match-otsakkeen saamallaan vahvalla tunnisteella. Palvelin vertaa versiota ennen kirjoitusta; esimerkissä muuttunut versio tuottaa 412-vastauksen. W/"r7" on heikko eikä täytä vahvaa vertailua. If-Match: * tarkistaa nykyisen esityksen olemassaolon, ei sen muuttumattomuutta lukemisen jälkeen.

Säilytä toisen toimittajan luonnos, lue nykyinen versio ja näytä erot ennen uutta päätöstä. Tunnisteen automaattinen vaihtaminen arvoon "r8" ja vanhan luonnoksen lähettäminen ohittaisi suojauksen. Tarkistuksen ja kirjoituksen on oltava tallennuksessa jakamattomia; kaksi samanaikaista pyyntöä samalla tunnisteella eivät saa molemmat korvata samaa versiota.

Samanaikaisuuden hallinta ei korvaa tunnistautumista, tietueen käyttöoikeuksia tai kenttien validointia. Se ei myöskään takaa ulkoisen kutsun kertaluonteisuutta. Testaa nämä erikseen ja kuvaa puuttuvat esiehdot; 428 voi edellyttää ehdollista pyyntöä.

Vieritä taulukkoa vaakasuunnassa nähdäksesi kaikki sarakkeet. Siirrä näppäimistöllä kohdistus taulukkoon ja käytä nuolinäppäimiä.

Kaksi toimittajaa, yksi nykyinen versio: kuvitteellinen testiketju
VaiheVersio ja pyyntöSopimuksen mukainen odotus
Molemmat lukevatETag: "r7"Kumpikin säilyttää tunnisteen luonnoksen mukana.
Ensimmäinen tallennusIf-Match: "r7" → versio "r8"Ensimmäinen korjaus säilyy.
Vanhentunut toinen tallennusIf-Match: "r7"; nykyinen versio "r8"412; tallennettua korjausta ei korvata.
Tietoinen yhteensovitusLue "r8", vertaa ja päätäSäilytä luonnos ja tarkista oikeudet ennen uutta kirjoitusta.

Testaa rajat ja käyttöoikeudet

Kokeile olemassa olevaa objektia, puuttuvaa objektia, virheellistä parametria ja luetteloa, joka on pidempi kuin yksi sivu. Tarkista seuraavalta sivulta häviöt tai toistot valitussa päivitysmallissa. ilmoittaa rajoituksia, joita API ei voi taata.

Käytä testitilejä eri käyttöoikeuksilla. yrittää lukea ja muuttaa sallitun laajuuden ulkopuolella synteettistä dataa käyttämällä. Tallenna odotetut tilat ja hyödylliset viestit paljastamatta sisäisiä jälkiä tai konfigurointisalaisuuksia.

Suunnittele muutos ja tuki

erottaa lisätty kenttä poistetusta kentästä tai muuttuneesta merkityksestä. Tunnista kuluttajat ennen yhteensopimatonta muutosta. Selitä siirtymäkausi ja kuinka havaita integraatiot edelleen käyttämällä aikaisempaa sopimusta.

Anna suoritettava esimerkki testiympäristöstä, testimatriisista ja teknisestä kontaktista. Yhdistä havaitut virheet dokumentoituihin esimerkkeihin julkaisun jälkeen. Ihanteelliseen tapaukseen rajoittuva dokumentaatio jättää integraattorit ilman ohjeita kieltäytymis- ja keskeytysten varalta.

ensisijainen dokumentaatio: OpenAPI-aloite – eritelmät.

viiteasiakirjat

Sisältö päivitetty

Aiheen dokumentoidut viitekohdat

Aiheen dokumentoidut viitekohdat
ViiteArvo tai syntaksiSoveltamisala
RFC 8259 · JSON
application/json · UTF-8Tavallinen JSON ei salli kommentteja tai loppupilkkuja; merkkijonot käyttävät kaksinkertaisia lainausmerkkejä.
RFC 3339 · Date-time
2026-10-22T09:00:00+02:00Selkeä aikasiirtymä yhdistää paikallisajan UTC-aikaan; esimerkki ei ole ajanvaraus.
HTTP · If-Match
If-Match: "r7" → 412If-Match vertaa vahvaa tunnistetta ennen kirjoitusta. Esimerkin sopimuksessa vanhentunut versio saa 412-vastauksen; luonnos säilytetään muutosten vertailuun.
HTTP · 428
428 · Precondition Required428 antaa palvelimen vaatia ehdollista pyyntöä. Kuvaa käyttö sopimuksessa; tilakoodi ei itsessään tarjoa lukitusta.

Päivämäärät kertovat lähteiden tarkistamisesta. Tiedot eivät ole sivuston auditointi tai yleinen vaatimustenmukaisuusvakuutus.

Erota HTTP-tila, JSON ja toiminnon tulos

Valitse kuvitteellinen viestinvaihto ja kokeile paikallista lukua. HTTP-onnistuminen, luettava JSON ja valmis toiminto on tarkistettava erikseen.

Katkelmat ovat puutteellisia ja käyttävät esimerkkiosoitteita. Koe luo Response-olion muistiin: se ei ota yhteyttä palvelimeen eikä simuloi verkkoa, välimuistia tai liiketoimintakäsittelyä.

200Uusi kokonainen esitys
Merkitys
Tässä katkelmassa palvelin vastaa ehdolliseen GET-pyyntöön JSON-rungolla ja demo-v2-validaattorilla.
Tarkistettava asia
Vertaa If-None-Match-, ETag- ja rungon revisiotietoja. Paikallinen koe jäsentää tämän esimerkin JSONin.
Huomioitavaa
Tila 200 ei takaa kelvollista JSONia tai oikeita liiketoimintatietoja. Onnistunut jäsentäminen ei vahvista omien tietojesi rakennetta.
Kuvitteellisen viestinvaihdon katkelma
GET /demo/catalogue
If-None-Match: "demo-v1"

HTTP/1.1 200 OK
ETag: "demo-v2"
Content-Type: application/json

{"revision":"demo-v2"}

202Hyväksytty, käsittely vielä kesken
Merkitys
202 kertoo hyväksymisestä käsittelyyn, ei valmistumisesta. Kuvitteellisen rungon tila on queued.
Tarkistettava asia
Säilytä DEMO-42 ja seuraa tilaa API-sopimuksen, käyttöoikeuksien ja uusintarajojen mukaan.
Huomioitavaa
Response.ok on true. Arvo tai luettava JSON ei todista valmistumista. Katkelman kentät ja seurantaosoite ovat kuvitteellisia sopimuksia.
Kuvitteellisen viestinvaihdon katkelma
POST /demo/jobs

HTTP/1.1 202 Accepted
Location: /demo/jobs/DEMO-42
Content-Type: application/json

{"job":"DEMO-42","status":"queued"}

204Pyyntö täytetty, ei vastausrunkoa
Merkitys
204 kertoo palvelimen täyttäneen pyynnön ilman vastaussisältöä. Katkelma ei lähetä JSONia.
Tarkistettava asia
Käsittele puuttuva runko sopimuksen mukaan. Selvitä, mitä vastaanottava päätepiste vahvistaa ennen tuloksen ilmoittamista vierailijalle.
Huomioitavaa
Tyhjän rungon JSON-jäsennys epäonnistuu, vaikka Response.ok on true. Webhook voi vahvistaa vain vastaanoton; myöhemmät toimet on tarkistettava erikseen.
Kuvitteellisen viestinvaihdon katkelma
POST /demo/events

HTTP/1.1 204 No Content

304Kopio vahvistettu, ei uutta runkoa
Merkitys
304 vastaa ehdolliseen pyyntöön: tallennettua esitystä voi käyttää uudelleen. Se ei toimita uutta runkoa.
Tarkistettava asia
Vertaa lähetettyä validaattoria saatavilla olevaan demo-v2-kopioon. Tulkinta riippuu myös tallennetusta kopiosta.
Huomioitavaa
Koe luo yksittäisen Response 304 -olion, ei HTTP-välimuistia. Todellisessa fetch-haussa selain voi palauttaa tallennetun vastauksen: verkon ja skriptin tilakoodit voivat erota.
Kuvitteellisen viestinvaihdon katkelma
GET /demo/catalogue
If-None-Match: "demo-v2"

HTTP/1.1 304 Not Modified
ETag: "demo-v2"

Tekniset lähteet : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

toiminnallinen validointimatriisi, joka mukautuu projektiin

Nämä ehdotetut kontrollit käyttävät kuvitteellisia tapauksia. Päätä, mitä käyttäytymistä tiimin kanssa odotetaan, kirjoita tulos muistiin ja määritä ratkaisemattomia eroja ennen julkaisemista.

Vieritä taulukkoa vaakasuunnassa nähdäksesi kaikki sarakkeet. Siirrä näppäimistöllä kohdistus taulukkoon ja käytä nuolinäppäimiä.

testitapaukset, odotetut tulokset ja hyödyllisiä todisteita
Asiaodotettu tulostodiste säilyttää
nykyiset ja puuttuvat resurssitJokainen tulos vastaa dokumentoitua tila- ja vastausmallia.pyyntö, vastaus ja vastaava sopimusesimerkki, joka on otettu testiympäristöstä.
alueen ulkopuolinen parametriKieltäytyminen on ymmärrettävää eikä paljasta sisäistä pinojälkeä.Julkinen viesti ja tulos säilytetään hyväksymismatriisissa.
Kaksi lupatasoaKielletty resurssi ei ole käytettävissä edes tunnetulla tunnisteella.Verrattiin tuloksia käyttämällä kahta synteettistä tiliä, joilla on selvästi erilaiset käyttöoikeudet.
sivutus ja vaihdettu suodatinTokenin käsittely ja matkan uudelleenkäynnistyskäyttäytyminen määritellään.tilaus, palautetut tunnisteet ja säännöt, jotka koskevat suodattimen muuttumista.

Usein kysyttyjä kysymyksiä

Riittääkö luotu dokumentaatio API:n testaamiseen?

Se auttaa lukemaan sopimusta, mutta käyttöoikeudet, puuttuvat tiedot, virheet, luettelot ja muutokset vaativat edelleen testausta. Vertaa esimerkkejä todellisiin testiympäristön vastauksiin.

Korvaako CORS käyttöoikeudet?

Ei. Ristialkuperäsäännöt eivät korvaa palvelun toimintaa ja objektin käyttöoikeuksia. Kuvaile nämä käyttöoikeudet ja testaa palvelinpuolen täytäntöönpano testitileillä.