Arvioi asiakkaan näkökulmasta
Taulukko on tarkistusapu, ei yleinen takuu. Lisäkenttä voi rikkoa tiukan lukijan ja uusi lueteltu arvo kattavan tapauskäsittelyn. Kartoita asiakkaat, kirjastot ja oletukset.
| Muutos | Tarkistettava riski | Tarvittava näyttö |
|---|---|---|
| Poista tai nimeä kenttä uudelleen | Lukeminen epäonnistuu | Selkeä siirtymä ja asiakastestit. |
| Lisää valinnainen kenttä | Tiukka lukija tai nimiristiriita | Nykyisten asiakkaiden testit. |
| Lisää vastausarvo luetteloon | Puutteellinen tapauskäsittely | Tuntemattomien arvojen käsittely. |
| Muuta oletusarvoa | Eri liiketoimintatulos | Vertaa tapauksia ilman annettua arvoa. |
Järjestä rinnakkaiselo
- Kuvaa vanhat ja uudet rakenteet, oletukset, virheet, sivutus ja oikeudet. Testaa sopimus edustavilla asiakastapauksilla.
- Valitse version valintatapa selkeästi. Erota palveluversio ja OpenAPI-asiakirjan versio; tarkista välimuistit ja yhdyskäytävät.
- Julkaise aikataulu, siirtymäohje ja yhteyspiste. Mittaa todellista käyttöä kohtuullisesti ja suunnittele tietojen kanssa yhteensopiva palautus.
Erota käytöstä poisto ja sulkeminen
Deprecation ilmaisee vanhentuneeksi merkityn resurssin; Sunset voi ilmoittaa odotetun saatavuuden päättymisen. Otsakkeet eivät siirrä asiakkaita. Tarkista jäljellä olevat käyttäjät, velvoitteet ja palautus ennen sulkemista.
Alkuperäiset lähteet
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Versio kuluttajavaikutuksen mukaan
Numeron lisääminen URL-osoitteeseen ei sinänsä säilytä olemassa olevia asiakkaita. Muutettu tyyppi, odotettu arvo, toiminta tai virhevaste voi olla yhteensopimaton, vaikka polku pysyisi samana.
- Inventaario aktiivisista asiakkaista ja havaitusta käytöstä.
- Testaa vanhempia asiakasversioita uutta sopimusta vasten.
- Julkaise rinnakkaiselojakso ja tarkista käyttö ennen käytöstä poistamista.
Ensisijainen lähde: IETF RFC 9457 — Problem Details for HTTP APIs. Aiheeseen liittyvä menetelmä: lue käytännön opas.
Asynkroniset API-tehtävät
Hyväksytty pyyntö ei osoita työn valmistumista.
- Tili, toiminto ja uudelleen käytettävä tunniste
- Tila, aika, kyselyväli ja vanheneminen
- Lopputulos, virhe, peruminen ja jäljelle jäävät vaikutukset
- Yksi sallittu tehtävä ja tarkistettu tulos keskeytyksen jälkeen
Toistettava hyväksyntätapaus
Kuvitteellinen esimerkki: tiedot eivät kuvaa asiakasta tai havaittua tulosta.
Näytä tapauksen tiedot
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Odotettu päätös
Tilakyselyn 200 ei tarkoita käsittelyn valmistumista. Peruutuspyynnön jälkeen ratkaisee vain vahvistettu lopputulos.
Peruutuspyyntö saapuu liian myöhään
Kuvitteellinen tapaus: sama tehtävä J-42, sekunteja lähetyksestä. Tilanimet kuuluvat esimerkin sopimukseen; HTTP ei määrää niitä.
| Aika | Vastaus ja tila | Perusteltu päätelmä |
|---|---|---|
| +0 s | HTTP 202 · pending | Hyväksytty käsittelyyn; lopputulosta ei ole vahvistettu. |
| +5 s | HTTP 200 · running | Tilakysely onnistui; tehtävä on yhä käynnissä. |
| +6 s | HTTP 200 · cancel_requested | Pysäytyspyyntö kirjattu; peruutusta ei ole vahvistettu. |
| +7 s | HTTP 200 · succeeded | Käsittely ehti ensin. Näytä vahvistettu onnistuminen ja tarkista vaikutukset; älä ilmoita peruutusta. |
Todistaako 202 työn valmistumisen?
Ei. Se vahvistaa käsittelyyn hyväksymisen, ei lopputulosta. Tarkista toiminnon tila.
Ensisijainen lähde: MDN — 202 Accepted. Aiheeseen liittyvä menetelmä: lue käytännön opas.
Ohjelmistopäivitys: allekirjoittajan muutoksen tarkistus
Selvitä, vastaako allekirjoitettu julkaisu yhä hyväksyttyä tuottajaa, rakennusta ja versiota.
- Kirjaa ennen paketin tarkistusta sallittu tuottaja, avain tai varmenneidentiteetti, myöntäjä ja rakennusprosessi. Yhdistä odotukset ohjelmistoon ja jo luotettuun vahvistuskanavaan. Tarkistettava paketti ei saa yksin määrittää omaa hyväksymiskäytäntöään.
- Vertaa vastaanotetun tiedoston tiivistettä todistuksen kohteeseen. Tarkista allekirjoitus sovituilla luottamusjuurilla, sitten identiteetti, rakentaja ja parametrit. Toisen identiteetin kelvollinen allekirjoitus ei täytä palvelun käytäntöä.
- Testaa ilmoitettu vaihto, odottamaton myöntäjä, puuttuva allekirjoitus ja eri tiedosto. Pidä julkaisu odottamassa, jos uusi identiteetti on vahvistamatta. Kirjaa hyväksyntä ja paluuvaihtoehto; allekirjoitus ei todista haavoittuvuuksien puuttumista.
Toistettava hyväksyntätapaus
Kuvitteellinen esimerkki: tiedot eivät kuvaa asiakasta tai havaittua tulosta.
Näytä tapauksen tiedot
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Odotettu päätös
Kuvitteellinen esimerkki: tiiviste ja allekirjoitus ovat kelvolliset, mutta allekirjoittaja eroaa hyväksytystä. Asennus odottaa muutoksen riippumatonta vahvistusta.
Ensisijainen lähde: SLSA v1.2 — Verifying artifacts. Aiheeseen liittyvä menetelmä: lue käytännön opas.
API: vanhentuminen ja poistuminen
Tämän kieliversion tarkemmat lähdekuvaukset ovat englanniksi.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23