REST API: áttekintés és hitelesítés

A Tutor LMS teljesen integrálódik a WordPress REST API-jával. Az adatokat JSON-kérésekkel olvashatod, a Pro bővítménnyel pedig létrehozhatod, módosíthatod és törölheted is. Az API a szokásos HTTP-igéket, az API-kulcsok jogosultsági szintjeit és felhasználói azonosítást adó tokeneket használ.

Fontos: a hitelesítés megváltozott. Az API-kulcsot és titkos kulcsot használó Basic Auth már nem működik. Az alkalmazásod a kulcsot és a titkos kulcsot egyszer, a bejelentkezéskor küldi el, és kap egy hozzáférési tokent, amely a végfelhasználót azonosítja. Az API-kulcs nem a kulcs tulajdonosaként viselkedik, a válaszok attól a felhasználótól függnek, akié a token.

Követelmények

• Tutor LMS 4.2 vagy újabb.
• Az ingyenes Tutor LMS csak olvasásra ad API-t: kurzusok, tanterv, kvízek, szerzők és értékelések, plusz a hitelesítési végpontok. Az adatot létrehozó, módosító vagy törlő útvonalakhoz (beiratkozások, feladatbeadások stb.) a Tutor LMS Pro kell.
• Az API HTTP-n és HTTPS-en is elérhető, de erősen ajánlott a HTTPS.

Kérés- és válaszformátum

A válaszok alapértelmezett formátuma JSON, és az erőforrások tulajdonságait is sima JSON-nal állítod. Minden sikeres kérés 200 OK állapotot ad. A legtöbb válasz ilyen keretben érkezik:

{
  "code": "success",
  "message": "Ember által olvasható üzenet",
  "data": {}
}

Általános tudnivalók:

1. A dátumok formátuma ÉÉÉÉ-HH-NN ÓÓ:PP:MP.
2. Az azonosítók egész számok.
3. A pénzösszegek (kurzusárak, végösszegek) két tizedesjegyű szövegként érkeznek.
4. Üres lista vagy hiányzó erőforrás esetén a válasz lehet 200-as állapotú "code": "not_found" kóddal és üres data résszel.
5. A válaszok attól a felhasználótól függnek, akié a hozzáférési token.

Hogyan működik a hitelesítés

Két hitelesítő adat dolgozik együtt:

• Az API-kulcs és a titkos kulcs az alkalmazást azonosítja, és a jogosultsági szintje határozza meg, mit tehet (Read, Write, Delete vagy All). Ezeket csak a bejelentkezéskor küldöd el.
• A hozzáférési token a végfelhasználót azonosítja. Rövid életű, és minden további kéréssel elküldöd. A frissítő token (refresh token) új tokenpárt ad újabb bejelentkezés nélkül, és vissza is vonható.

A folyamat:

1. Hozz létre egy API-kulcsot, és válaszd ki a jogosultsági szintjét.
2. Jelentkezz be a kulccsal és a titkos kulccsal (fejlécben), valamint a végfelhasználó felhasználónevével és jelszavával (a kérés törzsében). Kapsz egy hozzáférési és egy frissítő tokent.
3. Mentsd el a hozzáférési tokent, és küldd el minden kéréssel.
4. Ha a hozzáférési token lejár, a frissítő tokennel kérj új tokenpárt.
5. Kijelentkezéskor a frissítő token visszavonásra kerül.

1. lépés: API-kulcs létrehozása

Az API-kulcsot a Tutor LMS Pro → Eszközök → REST API oldalon hozod létre a + Új hozzáadása gombbal: kiválasztod a felhasználót és a jogosultsági szintet, majd a Generate gombbal létrehozod a kulcs és titkos kulcs párt. A részletes lépéseket lásd az Eszközök fejezetben.

https://minta-bolt.hu/wp-admin/admin.php?page=tutor-tools&sub_page=tutor_rest_api

A kép felső részén a tokenek élettartama állítható, alatta a kulcsok táblázata látszik (a képen még nincs kulcs).

A jogosultsági szintek:

Jogosultság	Mit engedélyez
Read	Olvasási kéréseket, például GET.
Write	Létrehozási és módosítási kéréseket.
Delete	Törlési kéréseket.
All	Mindháromat.

2. lépés: bejelentkezés a tokenekért

URL: https://oldalad-cime.hu/wp-json/tutor/v1/auth/login
Típus: POST

A kulcsot és a titkos kulcsot fejlécekben add meg:

Fejléc	Érték
Content-Type	application/json
Tutor-Api-Key	AZ_API_KULCSOD
Tutor-Api-Secret	A_TITKOS_KULCSOD

A kérés törzse:

Mező	Típus	Kötelező	Leírás
username	szöveg	igen	A felhasználó WordPress-neve vagy e-mail-címe.
password	szöveg	igen	A felhasználó jelszava.

{
  "username": "VEGFELHASZNALO_NEVE",
  "password": "VEGFELHASZNALO_JELSZAVA"
}

Sikeres válasz:

{
  "access_token": "HOZZAFERESI_TOKEN",
  "expires_in": 86400,
  "refresh_token": "FRISSITO_TOKEN",
  "user_id": 12,
  "display_name": "Minta Anna"
}

Az expires_in a hozzáférési token élettartama másodpercben. Az alapérték 86400 (1 nap), a 0 azt jelenti, hogy a token nem jár le. Ha az API-kulcs hiányzik vagy érvénytelen, a kérést a rendszer rest_forbidden hibával elutasítja.

3. lépés: hitelesített kérések

A hozzáférési tokent Bearer tokenként küldd el (az Authorization: Bearer <token> fejlécben; Postmanben az Authorization fülön a Bearer Token típust válaszd). A kulcsra és a titkos kulcsra a bejelentkezésen kívül nincs szükség. A token ahhoz a kulcshoz kötődik, amellyel létrejött, ezért a kulcs jogosultsági szintje továbbra is érvényes.

4. lépés: lejárt hozzáférési token megújítása

Ha a hozzáférési token lejárt, a frissítő tokennel kérhetsz új tokenpárt. Ehhez nem kellenek az API-kulcs fejlécek.

URL: https://oldalad-cime.hu/wp-json/tutor/v1/auth/refresh
Típus: POST

{
  "refresh_token": "A_FRISSITO_TOKENED"
}

A válasz ugyanolyan, mint a bejelentkezésnél: új hozzáférési és új frissítő token. A frissítő token ahhoz az API-kulcshoz kötődik, amellyel kiállították. Ha a kulcsot törölték vagy visszavonták, a kérés 403-as hibát ad.

5. lépés: kijelentkezés

URL: https://oldalad-cime.hu/wp-json/tutor/v1/auth/logout
Típus: POST

Mező	Típus	Kötelező	Leírás
refresh_token	szöveg	nem*	Az ehhez a frissítő tokenhez tartozó munkamenetet zárja le.
all	logikai	nem	Ha true, a felhasználó összes frissítési munkamenetét lezárja.

* Vagy a refresh_token-t add meg, vagy az all: true értéket érvényes hozzáférési tokennel az Authorization: Bearer vagy a Tutor-User-Token fejlécben.

Sikeres válasz: { "success": true }

Tokenek élettartama

A hozzáférési és a frissítő token élettartamát napokban, a Tutor LMS Pro → Eszközök → REST API oldalon, a tokenek élettartamát megadó mezőkben állíthatod.

Token	Alapérték	Megengedett tartomány
Hozzáférési token	1 nap	1 és 365 nap között
Frissítő token	30 nap	1 és 365 nap között

• A frissítő token élettartamának hosszabbnak kell lennie, mint a hozzáférési tokené.
• A 0 azt jelenti, hogy a token nem jár le. Ez erősen nem ajánlott, mert egy ellopott token örökre érvényes maradna.

Biztonsági tanácsok

• A kulcsokat, titkos kulcsokat és tokeneket a szerver oldalán tárold, soha ne tedd a böngészőben futó kódba vagy nyilvános tárolóba.
• Minden kéréshez HTTPS-t használj.
• Minden API-kulcsnak a legalacsonyabb szükséges jogosultsági szintet add.
• A frissítő tokent kezeld jelszóként, mert újabb hozzáférési tokenek kérhetők vele.
• A munkamenet végén jelentkezz ki, hogy a frissítő token visszavonásra kerüljön.

Hozzáférés és válaszok

A válaszok és a hozzáférés attól a felhasználótól függnek, akié a hozzáférési token, és az API-kulcs jogosultsági szintjétől.

• Kurzustartalom: a kurzus adatai, tanterve, témái, leckéi, bejelentései, kvízei, kvízválaszai és kvízpróbálkozásai csak akkor érhetők el, ha a kurzus nyilvános, a felhasználó beiratkozott rá, vagy a kurzushoz hozzáférő oktató vagy adminisztrátor. Egyébként az API 403-at ad. A Pro útvonalai (beiratkozások, feladatok, kvízpróbálkozások, kérdések és válaszok) azt is ellenőrzik, ki kéri az adatot és hozzáférhet-e az adott elemhez.
• Személyes adatok: a szerzők és kurzusok válaszában alapból csak a felhasználó azonosítója, megjelenített neve és „nicename” neve szerepel. A felhasználónév, az e-mail-cím, a regisztráció dátuma és az URL csak akkor jelenik meg, ha a kérő maga a felhasználó, rendelkezik a list_users joggal, vagy olyan kurzus oktatója, amelyre a felhasználó beiratkozott. Az értékelők e-mail-címére ugyanez a szabály vonatkozik.
• Kvízválaszok: a helyes válaszok a kvízválaszokból addig nem látszanak, amíg a tanuló le nem zár egy próbálkozást, kivéve, ha a kérő kezelheti a kurzust. A választásos kérdéseknél a lehetőségek is_correct nélkül érkeznek, más kérdéstípusoknál a válaszok üresek.
• Kvízpróbálkozások: a hívó csak a saját próbálkozásait kapja meg, kivéve, ha kezelheti a kurzust.

Követelmények útvonalanként

Útvonal	Módszer	Mi kell hozzá
/auth/login	POST	API-kulcs és titkos kulcs (Read vagy magasabb)
/auth/refresh	POST	Frissítő token
/auth/logout	POST	Frissítő token, vagy hozzáférési token all: true értékkel
/courses	GET	Hozzáférési token, Read
/courses/{id}	GET	Hozzáférési token, Read, hozzáférés a kurzus tartalmához
/course-contents/{id}	GET	Hozzáférési token, Read, hozzáférés a kurzus tartalmához
/topics	GET	Hozzáférési token, Read, hozzáférés a kurzus tartalmához
/lessons	GET	Hozzáférési token, Read, hozzáférés a téma kurzusának tartalmához
/course-announcement/{id}	GET	Hozzáférési token, Read, hozzáférés a kurzus tartalmához
/quizzes, /quizzes/{id}	GET	Hozzáférési token, Read, hozzáférés a kvíz kurzusának tartalmához
/quiz-question-answer/{id}	GET	Hozzáférési token, Read, hozzáférés a kvíz kurzusának tartalmához
/quiz-attempt-details/{id}	GET	Hozzáférési token, Read, hozzáférés a kvíz kurzusának tartalmához
/author-information/{id}	GET	Hozzáférési token, Read
/course-rating/{id}	GET	Hozzáférési token, Read

Ha a hívó nem hajthatja végre a kérést, az API 403 Forbidden választ ad.

Hibák

HTTP-állapot	Hibakód	Jelentés
400 Bad Request	INVALID_PARAM	Érvénytelen vagy hiányzó paraméter a kérésben.
401 Unauthorized	UNAUTHORIZED	A hozzáférési token hiányzik, érvénytelen vagy lejárt.
403 Forbidden	FORBIDDEN	Az API-kulcs jogosultsága vagy a felhasználó hozzáférése nem engedi az erőforrást vagy műveletet. Akkor is ez jön, ha a frissítő token API-kulcsa érvénytelen vagy visszavont.
404 Not Found	NOT_FOUND	A kért erőforrás nem található.
405 Method Not Allowed	METHOD_NOT_ALLOWED	Az erőforráshoz nem engedélyezett a használt HTTP-módszer.
408 Request Timeout	REQUEST_TIMEOUT	A szerver időtúllépést jelzett a kérés végrehajtása közben.
500 Internal Server Error	INTERNAL_SERVER_ERROR	A szerver váratlan hibába ütközött.
502 Bad Gateway	BAD_GATEWAY	Érvénytelen válasz érkezett egy felsőbb szerverről.
504 Gateway Timeout	GATEWAY_TIMEOUT	Az átjáróként működő szerver nem kapott időben választ.
505 HTTP Version Not Supported	HTTP_VERSION_NOT_SUPPORTED	A szerver nem támogatja a kérésben használt HTTP-verziót.
507 Insufficient Storage	INSUFFICIENT_STORAGE	A szerver nem tudja tárolni a kérés teljesítéséhez szükséges adatot.
508 Loop Detected	LOOP_DETECTED	A szerver végtelen ciklust észlelt a kérés feldolgozásakor.

A WordPress hibái a szabványos REST-hibaformátumot használják (code, message és data.status). Például hiányzó vagy érvénytelen API-kulcs a bejelentkezésnél:

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": { "status": 401 }
}

Csak a 400, 401, 403 és 500 állapotú hibák származnak a Tutor LMS-től, a többit a WordPress kezeli.