Verziók és kompatibilitás

Az API-nak egy főverziója van, a /v1, és ez csak bővül. A ma megírt integráció az új funkciók megjelenésével is tovább működik: semmit, amire támaszkodik, nem neveznek át, nem távolítanak el, és nem kap új jelentést.

A verziószám

Az API-nak verziószáma van, például 1.62.0. Minden kiadással változik:

• az alverzió száma, ha valami bővül: egy végpont, egy mező, egy esemény;
• a javítóverzió száma, ha csak egy leírást vagy egy üzenet szövegét javítják, és semmi más nem változik.

Hogy egy cím melyik verziót szolgálja ki, bármikor lekérdezheted:

A GET /v1/health válaszában is van version, de az a címet kiszolgáló Sursa-kiadás verziója, nem az API verziója.

Alverziót nem választhatsz: minden kérést az aktuális verzió szolgál ki. Az alábbi szabályoknak köszönhetően ez biztonságos.

Mi változhat a /v1 alatt

Ezek a változások bármely alverzióban megjelenhetnek. Úgy írd meg az integrációdat, hogy ne romoljon el tőlük:

• Új végpontok.
• Új opcionális paraméterek és kérésmezők. A nélkülük küldött kérések ugyanúgy viselkednek, mint korábban.
• Új mezők a válaszokban, az objektumokban és az eseményekben.
• A válaszok felsorolásainak új értékei, például egy új kártyaállapot vagy egy új eseménytípus.
• Új hibakódok és új válaszfejlécek.
• Enyhébbé váló korlátok: nagyobb maximális hossz, szélesebb tartomány.
• A hibák átfogalmazott message szövegei és átfogalmazott leírások.

Mit kell elviselnie a kódodnak

• Hagyd figyelmen kívül az ismeretlen mezőket. Ne hibázz, ha egy válaszban több mező van, mint amire számítasz, és ne használj olyan szigorú sémákat, amelyek elutasítják őket.
• Fogadd el az ismeretlen enumértékeket. A válaszok minden felsorolása bővülhet. Az ismeretlen értéket „egyéb” értékként kezeld, ne hibaként.
• Hagyd ki az ismeretlen eseménytípusokat, a webhookokban és az adatfolyamokban egyaránt.
• Az ismeretlen hibakódokat a HTTP-állapotkódjuk szerint kezeld: lásd: Hibák.
• Ne függj a mezők sorrendjétől a JSON-objektumokban, sem az üzenetek pontos szövegétől.

Ami soha nem változik a /v1 alatt

• Útvonalat, paramétert, mezőt vagy enumértéket soha nem neveznek át és nem távolítanak el.
• Egy mező típusa soha nem változik, és egy mező soha nem kap új jelentést, például új mértékegységet.
• A ma elfogadott kérést később nem utasítják el.
• A sikeres válasz állapotkódja ugyanaz marad.
• A hibakódok megtartják a jelentésüket, és a hibaválaszok detail mezője megtartja a formáját.
• Az eseménytípusokat soha nem nevezik át és nem távolítják el, a data mezőjük pedig csak új mezőkkel bővül.

Nem kompatibilis változások

Ha egyszer mégis nem kompatibilis változásra lenne szükség, az új főverzióként jelenik meg, például /v2 néven, a /v1 mellett. A /v1 változatlanul tovább működik, és a kettő egymás mellett fut.

Ha egy útvonalat ki fognak vezetni:

1. A specifikációban deprecated jelölést kap, és a változásnapló feltünteti azzal a dátummal, amikor kikapcsolják.
2. A válaszai a Deprecation: true és a Sunset: <date> fejlécet tartalmazzák.
3. A bejelentés után legalább 180 napig tovább működik. Azokat a szervezeteket, amelyeknek az API-kulcsai használják, legalább 90 nappal előre írásban értesítik.
4. A kivezetés dátuma után további 90 napig 410 választ ad az api.gone kóddal.

Figyeld a Deprecation fejlécet a naplóidban vagy a monitorozásban: ez a legkorábbi jel arra, hogy egy általad használt útvonal megszűnik.

Naprakészen maradni

A portál változásnaplója minden kiadást felsorol azzal együtt, hogy mi bővült és mi vált elavulttá. Mielőtt frissítenéd a saját integrációdat, vesd össze a kódját azokkal a bejegyzésekkel, amelyek annak a verziónak a megjelenése óta születtek, amelyre építetted.