Ką API gali padaryti jūsų turinio komandai
API sujungia dvi skaitmenines sistemas nereikalaujant, kad vartotojai kiekvieną kartą kopijuotų ir įklijuotų turinį. Pavyzdžiui, turinio valdymo sistema (CMS) gali nusiųsti pasirinktą tekstą į kalbos atpažinimo paslaugą ir gauti rezultatą atgal. Turinys lieka redakcijos komandai pažįstamoje CMS, o techninis ryšys tvarko mainus fone.
API automatiškai nenusprendžia, kuris turinys turėtų būti publikuojamas. Ji pateikia aiškiai apibrėžtą būdą, kaip pateikti duomenų užklausas ir pateikti rezultatus. Komanda vis tiek nustato, kuris puslapis yra redaguojamas, kuri versija yra šaltinis ir ar rezultatą reikia peržiūrėti prieš publikuojant. Šis atskyrimas apsaugo redakcinę atsakomybę.
Todėl gera pradžia nereikalauja visiško automatizavimo. Vieno, dažnai naudojamo turinio tipo pakanka, kad būtų galima suprasti jo privalumus. Tai galėtų būti paslaugos aprašymo tekstas. Jei siuntimas, gavimas, peržiūra ir išsaugojimas ten veikia patikimai, vėliau galima pridėti papildomą turinį ant tvirto pagrindo. Ši ribota pradžia taip pat aiškiai parodo, ar ryšys iš tikrųjų taupo laiką.
Pradėkite nuo aiškaus naudojimo atvejo
Prieš pasirinkdami techninius nustatymus, pageidaujamas darbo eigos procesas turėtų būti apibrėžtas kasdienine kalba. Pavyzdžiui, redaktorius atidaro publikuoto puslapio tekstą, užklausia suprantamesnės versijos ir gauna juodraštį CMS sistemoje. Jis palygina abi versijas, atlieka pakeitimus ir tik tada publikuoja. Šiame pavyzdyje aiškiai apibrėžiamas turinys, aktyviklis ir rezultatas.
Neaiškūs tikslai greitai lemia perkrautą integraciją. Teiginys „Norime apdoroti visą turinį per API“ palieka atvirą klausimą, ar bus įtraukta navigacija, formos, metaduomenys ar senesni dokumentai. Geresnis, konkretesnis klausimas būtų toks: ar galime perkelti pagrindinį naujų patarimų puslapių tekstą ir grąžinti rezultatą kaip nepublikuotą juodraštį? Tai leidžia pateikti prasmingą atsakymą.
Apribojimai taip pat yra naudojimo atvejo dalis. Galbūt iš pradžių reikėtų neįtraukti asmeninių žinučių, teisinių pranešimų ar tekstų, kuriuose yra konfidencialių projekto duomenų. Tokie sprendimai nėra techninis trūkumas. Jie sukuria valdomą sritį, kurioje redakcijos komanda ir IT gali nustatyti, kuris turinys yra tinkamas, o kur reikia papildomo dėmesio. Aiškus neįtraukimas neleidžia testui netyčia tapti visuotinai prieinamu.
Prašymų ir atsakymų supratimas be techninio žargono
Pateikus užklausą, sistema siunčia duomenis nurodytu API adresu. Tai apima patį turinį ir informaciją, apibūdinančią jo apdorojimą. Tai gali būti pageidaujamas kalbos formatas, šaltinio kalba arba vidinė nuoroda. API dokumentacijoje nurodoma, kuri informacija yra privaloma ir kokiu formatu jos tikimasi.
Atsakyme pateikiamas prašomas rezultatas arba aiškus pranešimas, paaiškinantis, kodėl jo nepavyko pateikti. CMS turi atskirti šiuos du dalykus. Sėkmingai perduoto teksto negalima painioti su klaidos pranešimu. Taip pat tuščio atsakymo negalima išsaugoti kaip baigto turinio ar net netyčia publikuoti.
Turinio komandai ypač svarbu žinoti rezultato šaltinį. Aiški nuoroda susieja atsakymą su teisingu šaltinio tekstu. Kai vienu metu redaguojami keli puslapiai, tai padeda išvengti painiavos. Be to, turėtų būti aišku, kuri šaltinio kodo versija buvo pateikta, kad vėlesni pakeitimai nebūtų perrašyti nepastebėti. Laiko žyma ir redagavimo būsena padeda teisingai suskirstyti senesnius atsakymus į kategorijas.
Prieigos duomenis traktuokite kaip raktą
Daugeliui API reikalingas slaptas prieigos raktas. Tai nurodo paslaugai, kuri sistema teikia užklausą ir kokie leidimai taikomi. Šis raktas neturėtų būti įtrauktas į puslapio tekstą, ekrano kopiją ar viešai prieinamą naršyklės kodą. Jei jis ten būtų matomas, neįgalioti asmenys galėtų jį nukopijuoti ir siųsti užklausas įmonės vardu.
Saugi vieta yra serverio pusėje, specialioje paslapčių valdymo sistemoje. Ten raktą galima naudoti neperduodant jo svetainės lankytojams. Skirtingos aplinkos turėtų turėti savo prieigos duomenis. Tai leidžia blokuoti arba atnaujinti prieigą prie testų, nereikalaujant paveikti veikiančios svetainės.
Leidimai turėtų leisti tik tai, ko iš tikrųjų reikia integracijai. Sistemai, kuri perduoda tekstą, nereikia bendros administratoriaus prieigos prie kitų paskyrų ar paslaugų. Jei raktas netyčia pažeidžiamas, turi būti įmanoma jį atšaukti ir pakeisti. Aiški atsakomybė neleidžia pažeistiems prieigos duomenims ilgai išlikti aktyviems ir nepastebėtiems. Reguliarus atnaujinimas dar labiau apriboja nepastebėto praradimo pasekmes.
Turinio perkėlimas ir jo reikšmė
Žiniatinklio tekstas retai kada susideda iš vienos didelės pastraipos. Antraštės, įžangos, paantraštės, nuorodų tekstas ir vaizdų aprašymai atlieka skirtingas funkcijas. Jei visi šie elementai sujungiami be jokių žymėjimų, rezultatas gali sulieti šiuos vaidmenis. Todėl užklausa turėtų aiškiai nurodyti, kuris tekstas priklauso kuriam turinio elementui, o kurie elementai turi likti nepakeisti.
Konkretus pavyzdys yra nuoroda su tekstu „Teikite paraišką dabar“. Matomas tekstas gali būti redaguojamas, tačiau tikslinis URL neturi būti prarastas. Tas pats pasakytina ir apie vietos žymeklius susitikimo patvirtinime, pvz., vardą, pavardę ar datą. Techninius žymeklius reikia apsaugoti, o aplinkinį tekstą galima pakeisti suprantamu būdu.
Kontekstas taip pat pagerina rezultatą. Sakinys „Galite pateikti paraišką čia“ vargu ar yra vienareikšmis be ankstesnės pastraipos. Užuot siuntus atskirus sakinius, integracija gali perduoti protingai ribotą dalį. Tuo pačiu metu ji neturėtų siųsti visos duomenų bazės, jei reikia tik vienos pastraipos. Taip išlaikoma tinkama prasmės, duomenų kiekio ir duomenų apsaugos reikalavimų pusiausvyra. Antraštės dažnai suteikia pakankamai konteksto, visiškai neatskleisdamos gretimų puslapių.
Klaidų aptikimas žmonėms suprantamu būdu
API gali būti laikinai nepasiekiama, atmesti užklausą arba užtrukti ilgiau nei tikėtasi. Tai nėra priežastis prarasti originalų turinį. CMS turėtų saugiai saugoti originalią versiją ir nurodyti, kad rezultatų dar nėra. Redakcijos komandai reikia aiškaus pranešimo, o ne tik techninio numerio be paaiškinimo.
Skirtingoms klaidoms reikia skirtingų atsakymų. Jei trūksta privalomo lauko, pakartotinis bandymas su nepakeistais duomenimis paprastai nepadės. Vėlesnis bandymas gali būti vertas trumpo sutrikimo atveju. Jei prieigos raktas negalioja, apie tai reikia informuoti atsakingą techninį asmenį. Aiškūs pranešimai padeda išvengti nesėkmingų bandymų ir nereikalingo netikrumo.
Daliniai rezultatai taip pat turi būti atpažįstami. Jei apdorotos tik devynios iš dešimties sekcijų, puslapis neturėtų būti rodomas kaip visa versija. Trūkstama sekcija turėtų likti matoma ir vėl redaguojama. Redaktoriams labai svarbu, kad jie visada žinotų, kuris turinys yra patvirtintas, o kuris dar laukia patvirtinimo. Vien laiko žyma nepakeičia šio aiškaus būsenos indikatoriaus.
Pateikti rezultatus redakcinei peržiūrai
API rezultatas iš pradžių turėtų būti rodomas kaip juodraštis, jei jo turiniui reikalingas žmogaus patvirtinimas. Redakcijos komanda turi galėti lengvai palyginti originalią ir galutinę versijas. Tai ne tik pakeisti žodžiai. Vardai, skaičiai, sąlygos ir instrukcijos nusipelno ypatingo dėmesio, nes net ir maži nukrypimai gali turėti reikšmingų pasekmių.
CMS turėtų leisti redaguoti neperrašant visų redakcinių pakeitimų kito techninio prašymo metu. Aiškus versijų žymėjimas padeda: kas buvo gauta iš API, kas buvo pakeista vėliau ir koks šaltinis buvo naudojamas? Ši informacija suteikia komandai pasitikėjimo, kai keli žmonės dirba su tuo pačiu puslapiu.
Sąmoningas atmetimas taip pat yra tinkamo naudoti rezultato dalis. Jei pateikta versija netinka, redakcijos komanda turėtų galėti laikytis esamo teksto arba pateikti naują užklausą su geresniu kontekstu. Integracija yra naudinga, kai ji padeda priimti sprendimus. Ji neturėtų daryti spaudimo žmonėms skelbti netinkamo pasiūlymo. Atmetimas neturėtų pakenkti jau patvirtintai versijai.
Testavimas bandymų sistemoje su tikrais turinio tipais.
Prieš diegiant ryšį viešojoje svetainėje, jį reikėtų išbandyti atskiroje aplinkoje. Tai leidžia klaidoms atsirasti nepaveikiant faktinių puslapių. Testo tekstai turėtų būti panašūs į tikrąjį turinį: trumpi pranešimai, ilgi vadovai, nuorodos, specialūs simboliai ir laukai su vietos rezervavimo ženklais atskleis įvairius perdavimo trūkumus.
Paprastas pavyzdinis tekstas tik įrodo, kad atsakymas iš principo gautas. Turinys su keliomis pastraipomis, neįprastai ilgais žodžiais arba simboliais iš skirtingų kalbų yra sudėtingesnis. Tuščias tekstas, labai didelė įvestis ir pasibaigusi prieiga taip pat turėtų būti tinkamai tvarkomi. Tai atskleis, kaip integracija veikia ne idealiomis sąlygomis.
Redakcinis testavimas papildo techninę peržiūrą. Redaktorius gali patikrinti, ar naujas juodraštis rodomas numatytoje vietoje ir ar jį galima lengvai palyginti. Jis gali nustatyti, kada ataskaita yra techniškai teisinga, bet nesuprantama. Ryšys yra tinkamas naudoti tik tada, kai patikimai veikia ir duomenų mainai, ir kasdienio turinio kūrimas. Net pakaitiniai darbuotojai turėtų sugebėti atpažinti atviro redagavimo būseną be išankstinių žinių.
Taupiai ir skaidriai apdorokite duomenis.
Kiekvienoje užklausoje turėtų būti tik tie duomenys, kurie būtini jos rezultatui gauti. Vardai, el. pašto adresai ar vidinės pastabos nebūtinai priklauso tekstui vien dėl to, kad jie saugomi toje pačioje sistemoje. Prieš integraciją reikėtų išsiaiškinti, kurie duomenys nepatenka į jūsų atsakomybės sritį, kur jie tvarkomi ir kiek laiko saugomi.
Žurnalai padeda suprasti klaidas, tačiau juose gali būti neskelbtinos informacijos. Trikčių šalinimui dažnai pakanka nuorodos, laiko ir klaidos tipo. Į žurnalus nereikėtų neatsargiai įtraukti viso teksto turinio ar slaptų raktų. Prieiga prie šios informacijos turi būti apsaugota taip pat kruopščiai, kaip ir pats ryšys.
Skaidrumas taip pat labai svarbus vidiniam bendradarbiavimui. Redakcijos darbuotojai, duomenų apsaugos ir IT specialistai turėtų vienodai suprasti, kas siunčiama ir kokiu tikslu. Jei vėliau pasikeičia turinio tipas ar paslauga, šį supratimą reikia dar kartą patvirtinti. Produkto aprašymas, kuris anksčiau buvo laikomas nekeliančiu problemų, nėra pakankamas pagrindas apdoroti suasmenintus konsultacinius laiškus. Nauji CMS laukai taip pat gali netyčia įtraukti papildomų duomenų į užklausą.
Patikimas ryšys kyla iš aiškumo.
Sėkminga API integracija neprasideda nuo kuo daugiau funkcijų. Ji prasideda nuo aiškaus turinio naudojimo, saugaus ryšio ir suprantamo grįžimo į CMS. Kai redakcijos darbuotojai ir IT specialistai gali aprašyti tą patį procesą, techninius sprendimus lengviau peržiūrėti, o visas kylančias problemas galima greičiau priskirti teisingam komponentui.
Kasdienėje praktikoje patikimi perėjimai yra nepaprastai svarbūs. Siunčiamas teisingas turinys, jo struktūra išlieka atpažįstama, klaidos nekenkia šaltiniui, o patikrinama rezultato versija pasiekia numatytą vietą. Prieigos duomenys ir neskelbtina informacija lieka apsaugoti. Šios savybės paverčia veikiančią užklausą naudingu turinio valdymo įrankiu. Jos taip pat palengvina trikčių šalinimą, jei vėliau pasikeičia paslauga ar turinys.
Tik po šio pradinio etapo prasminga plėstis į kitų tipų puslapius arba didesnius kiekius. Kiekvienas naujas turinio elementas gali sukelti skirtingus laukus, rizikas ir redakcinius klausimus. Patikrintas branduolys palengvina šį išplėtimą aklai neperkeliant senų prielaidų. Tai užtikrina, kad integracija išliktų suprantama, valdoma ir orientuota į realią naudą skaitytojams. Augantis naudojimas ir toliau reikalauja to paties atsekamo ryšio tarp šaltinio ir rezultato.