A programozói interfész (API) működése

Az API URL hívásokkal működik, és a get paraméterekkel paraméterezhető. Az eredményt egyetlenegy stringben adja vissza, ami szintén URL kódolt változó és érték párokból áll. Ez a módszer rendkívül egyszerűen használható tetszőleges platformon és programozási környezetben.

Az egyik leggyakrabban elterjedt webes programozási nyelvhez, a php-hez példa programkódokat is mellékelünk. A php-s példakód alapján könnyen megírható más nyelven is a kód.

Az API nem teljeskörű, nem lehet tehát a ListaMester összes funkcióját elérni vele, hiszen erre rendszerint nincs is szükség. A jelenleg elérhető funkciók a csoporttagok manipulációjára szolgálnak (feliratkozás, leiratkozás, adatok listázása és módosítása). Az API nem támogatja a levélküldést és a különféle beállítások módosításait.

Működési elv, alapszabályok

A ListaMesterben az adatok csoporthoz kötve vannak tárolva (a csoport a ListaMesterben lehet címlista vagy kérdőív). Minden csoportnak különféle adatmezői lehetnek, de két adatmező mindig kötelező: a név és az email cím. Az egyes adatmezőkre nem a nevük alapján hivatkozunk az API kérésekben, hanem minden mezőnek van egy egyszerű (számokat is tartalmazó) azonosítója (pl. "f734"). A név és email cím hivatkozási azonosítója mindig "name" és "email". A csoportok azonosítóit és mezők azonosítóit egy kérésben lekérhetjük az egész adatbázisra. Erre szolgál a "listFieldIDs" parancs.

Minden egyes URL híváshoz szükségesek az autentikációs adatok, azaz a felhasználói azonosító szám, és a jelszó kódolt alakja. Ezek az "uid" és "pwd" paraméterek. A művelet jogosultsága ezzel mindig ellenőrizve van. A paraméterek értékeit a listatulajdonos a "Beállítások -> Programozói interfész" menüpontban tudja megnézni. Ismeretük nem ad teljes hozzáférést a ListaMester fiókhoz a programozó számára, hiszen nem fog tudni velük belépni a webes felületen, ám az API által támogatott műveletekhez elegendő: látni fog minden információt, a címlistákat, stb.

További kötelező paraméter a "cmd", ami az aktuális parancs típusát adja meg, (pl. getMemberData a csoporttag adatainak lekérése). Az egyes parancsok paramétereket igényelnek (pl. a getMemberData számára szükséges a csoporttag "mid" azonosítója, amit a getAllMembers parancs hívásával előzőleg már lekérdeztünk). A paraméterek pontos leírását alább a Referencia szakaszban megadjuk.

A hívások visszatérési értéke mindig tartalmaz egy status nevű változót, aminek értéke helyes futás esetén "OK", hiba esetén "ERR", valamint egy msg nevű változót, ami egy angol nyelvű hibaüzenet a hiba okáról (vagy "Done" ha status="OK").

Az alábbi referencia szakaszban található példa URL-ek működnek, a böngészővel lehet azonnal próbálni a hívásokat egy teszt adatbázison. Értelemszerűen lehetnek hibaüzenetek is a hívások eredményeiben, attól függően, hogyan néz ki éppen a teszt adatbázis.

Referencia - az API URL hívásai

A paraméterek között nem tüntetjük fel a két kötelező paramétert (uid,pwd). A paraméterek értékeit UTF-8 kódolással kell megadni és URL kódolni.