# REST API áttekintés

> A MainWP REST API v2 alapjai: elérési út, hitelesítés, jogosultsági körök, végpontcsoportok, OpenAPI-leírás és a régi v1 kompatibilitás.

A MainWP REST API-val a vezérlőpultot HTTP-n keresztül, programból is kezelheted. Az API a REST-szabványokat követi, JSON-ban válaszol, és HTTPS-kéréseket vár. A vezérlőpult címének elérhetőnek kell lennie attól a rendszertől, amely a kéréseket küldi. Egy csak helyben futó vezérlőpultot a külső eszközök általában nem érnek el.

Hitelesítésre két mód van:

- **Bearer token**: a `/mainwp/v2` útvonalhoz ez az ajánlott.
- **Consumer Key és Consumer Secret**: a régi `/mainwp/v1` útvonalhoz.

A kérések és válaszok pontos szerkezetét a MainWP nyilvános Postman-gyűjteménye (MainWP REST API v2) és az OpenAPI-leírás tartalmazza.

## Alap URL

Minden v2 végpont ezzel kezdődik:

```text
https://a-te-vezerlopultod.hu/wp-json/mainwp/v2/
```

A Bearer token így megy a kéréssel:

```bash
curl -H "Authorization: Bearer API_KULCS" \
  "https://a-te-vezerlopultod.hu/wp-json/mainwp/v2/sites/basic"
```

## API-kulcs létrehozása

1. Nyisd meg a **Beállítások → Közvetlen hivatkozások** oldalt a WordPress adminban, és válassz bármilyen szerkezetet, az **Egyszerű** kivételével. Egyszerű hivatkozásokkal a REST API nem működik.
2. A MainWP menüjében válaszd az **API-hozzáférés → API-kulcsok → API-kulcsok hozzáadása** oldalt, és add meg a kulcs nevét.
3. Válaszd ki a jogosultságokat az alapján, hogy milyen végpontokat fogsz hívni (lásd lent).
4. Ha az integrációdnak a `/mainwp/v1` útvonal kell, kapcsold be a **MainWP REST API v1 kompatibilitás bekapcsolása** kapcsolót. Ezt csak korlátozás nélküli vezérlőpult-adminisztrátor teheti meg. Ilyenkor a v2 kulcs mellé egy régi Consumer Key és Consumer Secret is létrejön.
5. Kattints a **Kulcs mentése** gombra, majd másold ki a létrejött adatokat, és tárold biztonságos helyen.
6. A v2 hívásokban az `Authorization: Bearer ...` fejlécben küldd el a tokent.

![Az új API-kulcs létrehozása: név, v1 kompatibilitás, jogosultságok és a Bearer token](./kepek/rest-api-api-kulcs-uj.webp)

*Az új API-kulcs létrehozása: név, v1 kompatibilitás, jogosultságok és a Bearer token* (https://minta-bolt.hu/wp-admin/admin.php?page=AddApiKeys)

A képen a **Jogosultságok** gombjait, a v1 kompatibilitás kapcsolóját és a kimásolható tokent látod.

Az API-kulcs (Bearer token) csak egyszer látszik, utólag nem lehet újra megnézni. Ha bekapcsoltad a v1 kompatibilitást, a Consumer Key és a Consumer Secret is csak egyszer jelenik meg.

### Jogosultsági körök

| Jogosultság | HTTP-metódusok | Mire jó |
|---|---|---|
| **Olvasott** | GET | Adatok lekérése |
| **Írás és törlés** | POST, PUT, PATCH, DELETE | Erőforrások létrehozása, módosítása és törlése |

A kulcsok kezelésének részleteit az [API-kulcsok](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-api-kulcsok/) fejezetben találod.

## Az API ki- és bekapcsolása

A MainWP REST API addig aktív, amíg legalább egy API-kulcs be van kapcsolva.

- Az API kikapcsolásához kapcsold ki az összes bekapcsolt kulcsot az **API-hozzáférés → API-kulcsok** oldalon.
- A kulcsok törléséhez egyenként a **Törlés** műveletet, vagy ugyanott a csoportos törlést használd.

## Végpontcsoportok

| Csoport | Mit kezel |
|---|---|
| Sites | Webhelylista, szinkronizálás, bővítmények, témák és webhelyműveletek |
| Clients | Ügyfelek, ügyfélmezők, ügyfélhez tartozó webhelyek és költségek |
| Tags | Címkék, valamint a hozzájuk tartozó webhelyek és ügyfelek |
| Updates | Frissítések listázása, futtatása, kihagyásuk kezelése |
| Costs | Költségkövető tételek, a hozzájuk kapcsolt webhelyek és ügyfelek, kötegelt műveletek |
| Users | Felhasználók listázása, létrehozása, módosítása, törlése, CSV-import, adminjelszavak |
| Settings | Általános, haladó, figyelési, e-mail és eszközbeállítások |
| Monitoring | Rendelkezésre állás figyelése: monitorok, események, szívverés, beállítások |
| API Keys | REST API-kulcsok listázása, létrehozása, szerkesztése, törlése |
| Posts | Webhelyeken átívelő bejegyzéslista és bejegyzésműveletek |
| Pages | Webhelyeken átívelő oldallista és oldalműveletek |
| Batch | Globális `/batch`, több vezérlőt átfogó műveletekhez |

A kiegészítők saját végpontjai külön fejezetben vannak: [Kiegészítők végpontjai](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-kiegeszitok/).

A részletes végpontfejezetek: [Webhelyek](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-webhelyek/), [Ügyfelek és költségek](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-ugyfelek-koltsegek/), [Bejegyzések és oldalak](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-bejegyzesek-oldalak/), [Beállítások](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-beallitasok/), [Monitorok](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-monitorok/), [Kötegelt műveletek](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-kotegelt-muveletek/).

## OpenAPI-leírás

A teljes v2 API gépi olvasású, OpenAPI 3.1.0 formátumú leírása a MainWP dokumentációs tárolójában érhető el, `openapi.yaml` néven. Importálhatod Postmanbe, generálhatsz belőle kliens kódot, vagy saját eszközöknek is átadhatod. Minden v2 végpontot lefed, a kiegészítők útvonalait is. Utóbbiak `x-requires-extension` jelölést kapnak, mert csak akkor válaszolnak, ha a megfelelő kiegészítő telepítve van. Az `info.version` mező azt a vezérlőpult-verziót jelzi, amelyhez a leírás készült.

## Régi v1 kompatibilitás

A MainWP a visszafelé kompatibilitás miatt továbbra is támogatja a régi v1 végpontokat (`/wp-json/mainwp/v1/`). A v1 kulcsokat az **API-hozzáférés → API-kulcsok → API-kulcsok hozzáadása** oldalon lehet létrehozni a v1 kompatibilitás bekapcsolásával. Csak korlátozás nélküli vezérlőpult-adminisztrátor hozhat létre vagy szerkeszthet régi v1 kulcsot. A Team Control munkatársai akkor sem, ha a szerepkörük API-kulcs jogosultságot ad. A v2 kulcskezelő végpontok csak v2 kulcsokat hoznak létre és kezelnek, régi v1 adatokat nem.

```bash
curl -u "CONSUMER_KEY:CONSUMER_SECRET" \
  "https://a-te-vezerlopultod.hu/wp-json/mainwp/v1/sites"
```

A régi v1 kérés a hitelesítő adatokat egy `X-Api-Key` fejlécben is átadhatja, amely tartalmazza a `consumer_key` és a `consumer_secret` értékét.

Új integrációt mindig v2-re építs, a v1-et csak ott használd, ahol egy meglévő integráció még megköveteli.

## Hosszan futó frissítések válasza

Egyes frissítési végpontok háttérfolyamatot indítanak, és nem várják meg a végét: azonnal egy elindítási vagy sorba állítási visszaigazolást adnak.

```json
{
  "success": 1,
  "message": "Batch updates all started successfully.",
  "last_time_start_batch_updates": "2024-09-03T16:57:29"
}
```

A vezérlőpult verziójától és a futtatási módtól függően a válaszban `job_id` és `queued_count` mező is lehet. Ha ilyen választ kapsz, várd meg a folyamat végét, majd szinkronizáld a vezérlőpultot, vagy kérdezd le újra a frissítési végpontokat.

## Kapcsolódó fejezetek

- [API-kulcsok](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-api-kulcsok/)
- [Alkalmazásjelszavak](https://hub.hellowp.io/hu/plugins/mainwp/rest-api-alkalmazasjelszavak/)