Arvioitu lukuaika : 7 min · Julkaistu
Valitse Tehtävät ennen osoitteita
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ä.
| Esimerkin JSON-tunnus | Näytetty JavaScript-arvo | Tulkinta |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Turvallinen kokonaisluku esimerkissä |
| 9007199254740992 | 9007199254740992 | Tarkka, mutta turvallisen alueen ulkopuolella |
| 9007199254740993 | 9007199254740992 | Pyö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ä.
| Suunniteltu vastaus | Todennettu asia | Kuluttajan tarkistus |
|---|---|---|
| 201 Created | Resurssi luotu | Tarkista sopimuksen vaatima Location ja luotu tunniste |
| 202 Accepted | Käsittely hyväksytty, ei valmis | Säilytä seurantaviite ja odota lopputulosta |
| 204 No Content | Toiminto onnistui ilman vastaussisältöä | Älä pura tyhjää sisältöä JSON-muotona |
| 422 Unprocessable Content | Ohje ymmärretty mutta ei käsiteltävissä säännön mukaan | Lue 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
- Kaksi r7-lukua
- Ensimmäinen kirjoitus: r8
- Vanha kirjoitus: 412
- 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ä.
| Vaihe | Versio ja pyyntö | Sopimuksen mukainen odotus |
|---|---|---|
| Molemmat lukevat | ETag: "r7" | Kumpikin säilyttää tunnisteen luonnoksen mukana. |
| Ensimmäinen tallennus | If-Match: "r7" → versio "r8" | Ensimmäinen korjaus säilyy. |
| Vanhentunut toinen tallennus | If-Match: "r7"; nykyinen versio "r8" | 412; tallennettua korjausta ei korvata. |
| Tietoinen yhteensovitus | Lue "r8", vertaa ja päätä | Säilytä luonnos ja tarkista oikeudet ennen uutta kirjoitusta. |
- IETF · RFC 9110 § 13.1.1
IETF : Ehdolliset kirjoitukset ja esiehdot
- IETF · RFC 6585 § 3
428 · Precondition Required
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
- OpenAPI-aloite – eritelmät · Lähde tarkistettu
- IETF : RFC 8259: JSON numbers · Lähde tarkistettu
- TC39 : Number.isSafeInteger · Lähde tarkistettu
Sisältö päivitetty
Aiheen dokumentoidut viitekohdat
| Viite | Arvo tai syntaksi | Soveltamisala |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | Tavallinen JSON ei salli kommentteja tai loppupilkkuja; merkkijonot käyttävät kaksinkertaisia lainausmerkkejä. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Selkeä aikasiirtymä yhdistää paikallisajan UTC-aikaan; esimerkki ei ole ajanvaraus. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-Match vertaa vahvaa tunnistetta ennen kirjoitusta. Esimerkin sopimuksessa vanhentunut versio saa 412-vastauksen; luonnos säilytetään muutosten vertailuun. |
| HTTP · 428 | 428 · Precondition Required | 428 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.
