Mit nyújt egy API a tartalomkezelő csapatnak?
Egy API két digitális rendszert köt össze, így az embereknek nem kell minden alkalommal kimásolniuk és beilleszteniük a tartalmat. Egy szerkesztőségi rendszer például elküldhet egy kiválasztott szöveget egy nyelvi szolgáltatásnak, majd visszafogadhatja az eredményt. A tartalom a szerkesztőség számára a megszokott CMS-ben marad, miközben a műszaki kapcsolat a háttérben végzi az adatcserét.
Az API nem dönti el automatikusan, melyik tartalmat kell közzétenni. Egy világosan leírt lehetőséget biztosít adatok lekérésére és eredmények visszaadására. Továbbra is a csapat határozza meg, melyik oldalt kell feldolgozni, melyik változat szolgál forrásként, és szükséges-e ellenőrizni az eredményt a közzététel előtt. Ez az elválasztás megőrzi a szerkesztői felelősséget.
A jó kezdéshez ezért még nincs szükség teljes automatizálásra. Egyetlen, gyakran használt tartalomtípus elegendő az előnyök megértéséhez. Ilyen lehet egy szolgáltatás leíró szövege. Ha ennél megbízhatóan működik a küldés, a fogadás, az ellenőrzés és a mentés, később stabil alapra építve további tartalmak vonhatók be. A korlátozott indulás azt is megmutatja, hogy a kapcsolat valóban időt takarít-e meg.
Kezdje világosan meghatározott felhasználási esettel
A műszaki beállítások kiválasztása előtt hétköznapi nyelven kell rögzíteni a kívánt folyamatot. Egy szerkesztő például megnyitja egy közzétett oldal szövegét, közérthetőbb változatot kér, majd tervezetet kap a CMS-ben. Összehasonlítja a két változatot, módosítja az eredményt, és csak ezután teszi közzé. Ez a példa megnevezi a tartalmat, a kiváltó eseményt és az eredményt.
A nem egyértelmű célok gyorsan túlterhelt integrációhoz vezetnek. A "Minden tartalmat API-n keresztül szeretnénk feldolgozni" kijelentés nyitva hagyja, hogy a navigáció, az űrlapok, a metaadatok vagy a régi dokumentumok is ide tartoznak-e. Jobb egy szűkebb kérdés: Át tudjuk-e küldeni az új útmutatóoldalak főszövegét, és vissza tudjuk-e adni az eredményt közzé nem tett tervezetként? Erre érdemi válasz adható.
A korlátok is a felhasználási esethez tartoznak. Lehet, hogy eleinte ki kell zárni a személyes üzeneteket, a jogi határozatokat vagy a bizalmas projektadatokat tartalmazó szövegeket. Az ilyen döntések nem műszaki gyengeségek. Áttekinthető területet teremtenek, amelyen belül a szerkesztőség és az informatika felismerheti, mely tartalmak alkalmasak, és hol van szükség további körültekintésre. Az egyértelmű kizárás megakadályozza, hogy egy teszt észrevétlenül általános hozzáféréssé váljon.
Értse meg szakkifejezések nélkül a kérést és a választ
Egy kérés során a saját rendszer adatokat küld az API meghatározott címére. Ide tartozik maga a tartalom és a feldolgozását leíró adatok. Ilyen lehet a kívánt nyelvi forma, a forrásnyelv vagy egy belső hivatkozási azonosító. Az API dokumentációja határozza meg, mely adatok kötelezőek, és milyen formában várja őket.
A válasz tartalmazza a kért eredményt vagy egy érthető üzenetet arról, miért nem sikerült azt elkészíteni. A CMS-nek meg kell különböztetnie a kettőt. A sikeresen továbbított szöveget nem szabad összetéveszteni egy hibaüzenettel. Ugyanígy az üres választ sem szabad kész tartalomként elmenteni, vagy akár véletlenül közzétenni.
A tartalomkezelő csapat számára különösen fontos, honnan származik az eredmény. Egy egyértelmű hivatkozási azonosító összekapcsolja a választ a megfelelő kiinduló szöveggel. Ha egyszerre több oldalt dolgoznak fel, ez megakadályozza a keveredést. Annak is felismerhetőnek kell maradnia, hogy a forrásszöveg melyik változatát küldték el, így a későbbi módosítások nem íródnak felül észrevétlenül. Az időpont és a feldolgozási állapot segít helyesen besorolni a régebbi válaszokat.
Kezelje kulcsként a hozzáférési adatokat
Sok API titkos hozzáférési kulcsot kér. Ez jelzi a szolgáltatásnak, melyik rendszer küld kérést, és milyen jogosultságok érvényesek. Ez a kulcs nem kerülhet oldalszövegbe, képernyőképbe vagy a böngészőnek nyilvánosan elküldött kódba. Ha ott láthatóvá válna, idegenek lemásolhatnák, és a vállalat nevében küldhetnének kéréseket.
A biztonságos hely a szerveroldalon, egy erre szolgáló titokkezelő rendszerben van. Ott úgy használható a kulcs, hogy nem továbbítják a weboldal látogatóinak. A különböző környezetek saját hozzáférési adatokat kapjanak. Így egy teszthozzáférés letiltható vagy megújítható anélkül, hogy szükségtelenül érintené az éles weboldalt.
A jogosultságok csak azt engedjék meg, amire az integrációnak valóban szüksége van. Egy szövegeket továbbító rendszernek nincs szüksége más fiókok vagy szolgáltatások általános adminisztrátori hozzáférésére. Ha egy kulcs véletlenül ismertté válik, visszavonhatónak és lecserélhetőnek kell lennie. Az egyértelmű felelősségi kör megakadályozza, hogy a veszélyeztetett hozzáférési adatok sokáig észrevétlenül aktívak maradjanak. A rendszeres megújítás tovább korlátozza egy fel nem fedezett elvesztés következményeit.
A tartalmakat jelentésükkel együtt továbbítsa
Egy webes szöveg ritkán áll egyetlen nagy bekezdésből. A cím, a bevezetés, a közcímek, a hivatkozásszövegek és a képleírások eltérő feladatokat látnak el. Ha minden mezőt jelölés nélkül egymás mögé fűznek, az eredmény összekeverheti ezeket a szerepeket. A kérésből ezért derüljön ki, melyik szöveg melyik tartalmi elemhez tartozik, és mely elemeknek kell változatlanul maradniuk.
Konkrét példa erre egy "Kérelem benyújtása most" szövegű hivatkozás. A látható megfogalmazás módosítható, de a célcím nem veszhet el. Ugyanez vonatkozik az időpont-visszaigazolásban szereplő helyőrzőkre, például a névre vagy a dátumra. A műszaki jelöléseket védeni kell, miközben a környező mondat közérthető módon módosítható.
A szövegkörnyezet is javítja az eredményt. Az "Itt igényelheti" mondat az előző bekezdés nélkül alig egyértelmű. Elszigetelt mondatok helyett az integráció ésszerűen körülhatárolt szakaszt továbbíthat. Ugyanakkor ne küldjön el egy egész adatbázist, ha csak egy bekezdésre van szükség. Így a jelentés, az adatmennyiség és a védelem igénye észszerű arányban marad. A címsorok gyakran elegendő összefüggést biztosítanak anélkül, hogy teljes egészében felfednék a szomszédos oldalakat.
Kezelje közérthetően a hibákat
Egy API átmenetileg elérhetetlenné válhat, elutasíthat egy kérést, vagy a vártnál több időt igényelhet. Ez nem ok a kiinduló tartalom elvesztésére. A CMS biztonságosan őrizze meg a kiinduló változatot, és jelezze, hogy még nincs eredmény. A szerkesztőségnek egyértelmű üzenetre van szüksége, nem csupán magyarázat nélküli műszaki hibaszámra.
A különböző hibák eltérő reakciókat igényelnek. Ha hiányzik egy kötelező mező, az adatok változatlan újraküldése általában nem segít. Rövid üzemzavar esetén érdemes lehet később újra próbálkozni. Ha érvénytelen a hozzáférési kulcs, értesíteni kell az illetékes műszaki szakembert. A közérthető üzenetek megelőzik a sikertelen ismétléseket és a szükségtelen bizonytalanságot.
A részleges eredményeket is fel kell ismerni. Ha tíz szakaszból csak kilencet dolgoztak fel, az oldal nem tűnhet teljes változatnak. A hiányzó rész maradjon látható, és legyen újra feldolgozható. A szerkesztők számára mindenekelőtt az számít, hogy mindig tudják, melyik tartalom áll biztonságosan rendelkezésre, és mi van még függőben. Egy időbélyeg önmagában nem helyettesíti ezt a közérthető állapotjelzést.
Az eredményeket szerkesztői ellenőrzésre alkalmas módon adja vissza
Az API eredménye először tervezetként jelenjen meg, ha a tartalma emberi jóváhagyást igényel. A szerkesztőségnek könnyen össze kell tudnia hasonlítani a kiinduló és az eredményváltozatot. Nemcsak a módosított szavakról van szó. A nevek, számok, feltételek és cselekvési utasítások különös figyelmet érdemelnek, mert ezeknél a kis eltéréseknek is nagy következményei lehetnek.
A CMS tegye lehetővé a szerkesztést anélkül, hogy a következő műszaki lekérés felülírna minden szerkesztői módosítást. A változatok egyértelmű jelölése segít: Mi érkezett az API-tól, mit módosítottak utána, és melyik forrás szolgált alapul? Ezek az információk biztonságot adnak a csapatnak, ha többen dolgoznak ugyanazon az oldalon.
A tudatos elutasítás is egy használható eredmény része. Ha a kapott változat nem megfelelő, a szerkesztőségnek meg kell tudnia tartani a meglévő szöveget, vagy új kérést kell tudnia küldeni jobb szövegkörnyezettel. Az integráció akkor hasznos, ha támogatja a döntéseket. Nem kényszerítheti az embereket egy nem megfelelő javaslat közzétételére. Az elutasítás nem károsíthatja a már megerősített kiinduló változatot.
Valódi tartalomformákkal ellenőrizze a tesztkörnyezetben
Mielőtt a kapcsolatot a nyilvános weboldalon használnák, külön környezetben kell kipróbálni. Ott úgy is előfordulhatnak hibák, hogy közben nem módosulnak az aktuális oldalak. A tesztszövegek hasonlítsanak a valódi tartalmakra: a rövid közlemények, hosszú útmutatók, hivatkozások, különleges karakterek és helyőrzőket tartalmazó mezők a továbbítás eltérő gyengeségeit tárják fel.
Egy egyszerű mintaszöveg csak azt bizonyítja, hogy alapvetően érkezik válasz. Nehezebbek a több szakaszból álló tartalmak, a szokatlanul hosszú szavak vagy a különböző nyelvek karakterei. Az üres szöveget, a nagyon nagy bemenetet és a lejárt hozzáférést is érthetően kell kezelni. Így láthatóvá válik, hogyan viselkedik az integráció az ideális eseten kívül.
A szerkesztői tesztek kiegészítik a műszaki ellenőrzést. Egy szerkesztő megvizsgálhatja, hogy az új tervezet a várt helyen jelenik-e meg, és könnyen összehasonlítható-e. Észreveszi, ha egy üzenet műszakilag helyes, de érthetetlen. A kapcsolat csak akkor használható, ha az adatcsere és a mindennapi tartalmi munka egyaránt megbízhatóan működik. A helyettesítő munkatársaknak is előzetes tudás nélkül fel kell ismerniük egy folyamatban lévő feldolgozás állapotát.
Takarékosan és követhetően kezelje az adatokat
Minden kérés csak az eredményéhez szükséges adatokat tartalmazza. A nevek, e-mail-címek vagy belső jegyzetek nem tartoznak automatikusan egy szöveghez pusztán azért, mert ugyanabban a rendszerben tárolják őket. Az integráció előtt tisztázni kell, mely adatok hagyják el a saját felelősségi területet, hol dolgozzák fel őket, és mennyi ideig őrzik meg őket.
A naplók segítenek megérteni a hibákat, de maguk is tartalmazhatnak érzékeny információkat. A hibakereséshez gyakran elegendő egy hivatkozási azonosító, egy időpont és a hiba típusa. Teljes szöveges tartalmak vagy titkos kulcsok nem kerülhetnek meggondolatlanul a naplókba. Az ezekhez az információkhoz való hozzáférést ugyanúgy védeni kell, mint magát a kapcsolatot.
Az átláthatóság a belső együttműködéshez is fontos. A szerkesztőségnek, az adatvédelemért felelős csapatnak és az informatikának ugyanazt kell értenie azon, hogy mit és milyen célból küldenek el. Ha később megváltozik a tartalomtípus vagy a szolgáltatás, ezt a feltételezést újra ellenőrizni kell. Egy korábban problémamentes termékszöveg nem elegendő alap személyes tanácsadási levelek feldolgozásához. A CMS új mezői is észrevétlenül további adatokat vihetnek be egy kérésbe.
A megbízható kapcsolat az egyértelműségből épül fel
A sikeres API-integráció nem a lehető legtöbb funkcióval kezdődik. Világosan meghatározott tartalmi esettel, biztonságos kapcsolattal és a CMS-be történő közérthető visszavezetéssel indul. Ha a szerkesztőség és az informatika ugyanúgy tudja leírni a folyamatot, a műszaki döntések könnyebben ellenőrizhetők, a felmerülő problémák pedig gyorsabban hozzárendelhetők a megfelelő részhez.
A mindennapokban elsősorban a megbízható átmenetek számítanak. A megfelelő tartalmat küldik el, szerkezete felismerhető marad, a hibák nem veszélyeztetik a forrást, az eredmény pedig ellenőrizhető változatként a várt helyre kerül. A hozzáférési adatok és az érzékeny információk védve maradnak. Ezek a tulajdonságok tesznek egy működő kérésből használható tartalomkezelő eszközt. Akkor is megkönnyítik a hibakeresést, ha később megváltozik egy szolgáltatás vagy tartalom.
Csak ezután érdemes további oldaltípusokra vagy nagyobb mennyiségekre kiterjeszteni a használatot. Minden új tartalom más mezőket, kockázatokat és szerkesztői kérdéseket hozhat magával. A bevált alap megkönnyíti ezt a bővítést anélkül, hogy vakon átvennék a régi feltételezéseket. Így az integráció érthető, ellenőrizhető és az olvasók számára nyújtott tényleges előnyökre összpontosító marad. A növekvő használathoz továbbra is szükség van a forrás és az eredmény közötti követhető kapcsolatra.