Resurssit · 33
Kehitä API-sopimuksia menettämättä asiakkaita.
Kuvaile pyyntöjä, vastauksia ja virheitä; testaa versioita ja tee webhookeista turvallisia toistaa.
Päivitetty · 2 min
Mitä tämä opas auttaa saavuttamaan
- Kirjoita sopimus
- Selvitä virheet
- Testaa yhteensopivuus
- Suunnittele käytöstäpoisto
Pikatarkistus
- Mitkä asiakkaat käyttävät kutakin toimintoa?
- Onko virheillä vakaa tyyppi ja yhtenäinen tila?
- Voiko vanha asiakas sietää muutosta?
- Voivatko uudelleenyritykset kopioida toiminnon?
- Miten käytöstäpoisto ilmoitetaan ja tarkistetaan?
Vaiheittainen menetelmä
- 1
Varaston käyttäjät
Listaa toiminnot, asiakkaat, käyttötarkoitukset, versiot ja omistajat. Erota havaittu käyttö oletuksista ennen kentän muuttamista.
Toimitettava: sopimusriippuvuuskartta.
- 2
Kuvaile pyyntöjä ja vastauksia
Ylläpidä OpenAPI-kuvausta, joka sisältää skeemoja, realistisia esimerkkejä sekä onnistumis- ja epäonnistumisvastauksia. Tarkista se käynnissä olevaa palvelua vasten.
Tuotanto: versioitu sopimus ja vaatimustenmukaisuustestit.
- 3
Virheiden vakauttaminen.
Käytä HTTP-tiloja niiden semantiikan mukaisesti ja tarvittaessa RFC 9457:n mukaisesti dokumentoitua ongelmatyyppiä. Älä paljasta salaisuuksia yksityiskohdissa.
Tuotanto: testattu virheluettelo.
- 4
Luokittele muutos.
Tarkista pakolliset kentät, tyypit, arvot, toiminta, aikakatkaisut ja sivutus. Testaa vanhoja asiakasohjelmia uutta versiota vasten edustavilla tapauksilla.
Tuotanto: yhteensopivuusmatriisi ja versiopäätös.
- 5
Tee ilmoituksista vankkoja.
Suunnittele webhookien osalta todennus, järjestämätön toimitus, kaksoiskappaleet ja uudelleenyritykset. Tee käsittelystä idempotenttia, jos toisto on mahdollista.
Tuotanto: toisto- ja kuittausskenaario.
- 6
Julkaisu poistumispolulla
Julkaise siirtomuistiinpanot, rinnakkaiselojakso ja yhteystiedot. Mittaa vanhan version käyttöä ja poista käytöstä vasta, kun olet tarkistanut asiaankuuluvat kuluttajat.
Toimitettava: siirtosuunnitelma ja poistamisen todisteet.
Johdon indikaattorit
| Indikaattori | Mitä se mittaa | Ensimmäinen toimenpide |
|---|---|---|
| Sopimus | Toimintojen kuvaus ja palvelun toiminnan yhteensovittaminen | Eroavaisuuksien korjaaminen |
| Yhteensopivuus | Ennen muutosta testatut edustavat asiakkaat | Lisää puuttuvat tapaukset |
| Virheet | Dokumentoidut tyypit ilman arkaluonteisia tietoja | Viestien ja skeemojen tarkistaminen |
| Siirto | Vanhan version käyttö omistajan kanssa | Jäljellä olevien asiakkaiden avustaminen |
Yleisiä virheitä
- Oletus, että pelkkä versionumero säilyttää yhteensopivuuden
- Vain 200 vastauksen dokumentointi
- Sisäisen jäljityksen tai salaisuuden palauttaminen virhetilanteessa
- Oletus, että webhookit saapuvat kerran ja oikeassa järjestyksessä
Usein kysytyt kysymykset
Korvaako OpenAPI testauksen?
Ei. Vertaa kuvausta todellisiin vastauksiin ja kuluttajien tarpeisiin.
Vaatiiko jokainen muutos uuden version?
Ei. Tee päätös asiakasvaikutuksen ja sopimuskäyttäytymisen perusteella; yhteensopimattomat muutokset vaativat selkeän suunnitelman.
Miksi kirjoitusvirheitä?
Ne tarjoavat asiakkaille vakaan tavan erottaa ongelmat ja valita toimenpide.
Viralliset viitteet
Viitteet tukevat menetelmää. Sovita tarkastukset kontekstiisi; ne eivät ole sertifiointia. Alkuperäiset viitteiden otsikot ja lähdeasiakirjat voivat olla toisella kielellä.
