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

> A Tutor LMS REST API alapjai: követelmények, válaszformátum, API-kulcs, bejelentkezés tokenért, frissítés, kijelentkezés, jogosultságok és hibakódok.

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:

```json
{
  "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](https://hub.hellowp.io/hu/plugins/tutor-pro/kurzusok-eszkozok/) fejezetben.

![A REST API oldal a tokenek élettartamával és az API-kulcsok táblázatával](./kepek/fejlesztoknek-rest-api-kulcsok.webp)

*A REST API oldal a tokenek élettartamával és az API-kulcsok táblázatával* (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

```text
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. |

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

Sikeres válasz:

```json
{
  "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.

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

```json
{
  "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

```text
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:

```json
{
  "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.