Erota kuvaus ja toteutus
Kiinnitä työkalujen tukema määritysversio. Kuvaa parametrit, sisällöt, vastaukset ja turvallisuusvaatimukset. Sovelluksen ja yhdyskäytävän pitää yhä toteuttaa ilmoitetut vaatimukset.
| Osa | Kuvaa | Lisätarkistus |
|---|---|---|
| Skeema | Rakenne ja rajoitteet | Todellinen validointi ja liiketoimintasäännöt. |
| Kuvattu vastaus | Odotettu tila ja sisältö | Todellisten vastausten vastaavuus. |
| Turvallisuusvaatimus | Ilmoitettu mekanismi ja oikeudet | Toimintokohtainen oikeuksien valvonta. |
| Esimerkki | Yksi havainnollistava tapaus | Johdonmukaisuus, ei salaisuuksia ja rajatapaukset. |
Tarkista ennen jakamista
- Tarkista pakolliset kentät, tyypit, rajat, sivutus, virheet ja sisältötyypit. Käytä skeeman mukaisia kuvitteellisia esimerkkejä ilman salaisuuksia tai asiakastietoa.
- Vertaa kuvausta hallittuihin pyyntöihin ja vastauksiin. Testaa puuttuvat tunnisteet, riittämättömät oikeudet ja tilien erottelu.
- Tarkista ulkoiset viitteet ja niitä käsittelevät työkalut. Puhdista julkinen kuvaus ja suojaa yksityiset ympäristöt ja toiminnot.
Ylläpidä dokumentaatiota
Arvioi erot ja nimeä vastuuhenkilö. Generoitu asiakas tai esimerkki voi olla rakenteellisesti kelvollinen mutta ohittaa liiketoimintasäännön. Vuorovaikutteinen konsoli tarvitsee sopivan ympäristön, rajatut oikeudet ja merkityt tilaa muuttavat toimet.
Alkuperäiset lähteet
Vertaa OpenAPI:a käynnissä olevaan palveluun.
Hyödyllinen OpenAPI-kuvaus sisältää virhevastauksia, skeemoja ja esimerkkejä, joita asiakkaat todellisuudessa kohtaavat. Kun dokumentti ja API eroavat toisistaan, integraatio voi läpäistä demon ja epäonnistua tuotannossa.
- Vertaa onnistumis- ja virhetapauksia kuvaukseen.
- Dokumentoi valinnaiset arvot, sivutuksen ja toimintorajoitukset.
- Testaa edustavaa asiakasta ennen sopimuksen muuttamista.
Ensisijainen lähde: IETF RFC 9457 — Problem Details for HTTP APIs. Aiheeseen liittyvä menetelmä: lue käytännön opas.
ZIP ja TAR: pura tiedostot polku- ja resurssirajojen sisällä
Tarkista polut, linkit ja puretut tiedot ennen tiedostojen julkaisua.
- Pura uuteen ei-julkiseen hakemistoon vähimmäisoikeuksin. Hylkää absoluuttiset polut, hakemistosta nousut, tarpeettomat linkit ja erikoistiedostot. Tarkista ratkaistut kohteet ja ristiriidat kohdejärjestelmän sääntöjen mukaan, myös kirjainkoko. Tekstietuliite ei yksin todista rajausta.
- Aseta tiedosto- ja kokonaisrajat kirjoitetuille tavuille, merkinnöille, syvyydelle, ajalle ja prosessin resursseille. Pakattu tai ilmoitettu koko ei riitä. Hylkää tarpeettomat sisäkkäiset arkistot; muuten käytä yhteistä kokonaisbudjettia. Päivitä kirjasto ja suodattimet.
- Testaa ../, absoluuttinen polku, linkki, kaksoiskappale ja budjettiylitys. Keskeytys jättää erän julkaisematta eikä korvaa vanhoja tiedostoja. Tarkista tyypit ja sisältö ennen julkaisua; varmista kohde siivouksen yhteydessä.
Toistettava hyväksyntätapaus
Kuvitteellinen esimerkki: tiedot eivät kuvaa asiakasta tai havaittua tulosta.
Näytä tapauksen tiedot
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Odotettu päätös
Kuvitteellinen esimerkki: 2 MB pakattuna tuottaa 600 MB, kun budjetti on 100 MB. Pysäytä kirjoitettujen tavujen ylittäessä rajan, älä julkaise erää vaikka alkutiedostot näyttävät kelvollisilta.
Python — tarfile extraction filters and further verification
Takaako pieni arkisto tai suodatin turvallisuuden?
Ei. Pieni arkisto voi kasvaa suureksi. Lisää resurssirajat, polkusäännöt ja purettujen tiedostojen tarkistus.
Ensisijainen lähde: Python — tarfile extraction filters and further verification. Aiheeseen liittyvä menetelmä: lue käytännön opas.
API-virheet: tyypit, tilat ja todisteet
Tämän kieliversion tarkemmat lähdekuvaukset ovat englanniksi.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5