13. B 14. A REST API alkalmazás fő követelményei

Az eddigiekben számos megoldással ismerkedtünk, hogyan hajthatunk végre különféle műveleteket. A záródolgozat kimeneti követelménye, hogy az alkalmazásnak meg kell felelnie a RESTful API követelményeinek. A következőkben megnézzük, hogy melyek ezek a követelmények, melyet később a gyakorlatba is átültetünk.

1. Kliens-szerver architektúra

A REST API egyértelműen elválasztja a klienst (például egy böngésző, mobilalkalmazás vagy más API-felhasználó) és a szervert. A szerver nem tárol kliens oldali állapotokat (stateless), csak válaszokat küld a kliens által küldött kérésekre. Ez a felépítés biztosítja a feladatok tiszta szétválasztását.

2. Stateless (Állapotmentesség)

A RESTful API-k stateless-ek, ami azt jelenti, hogy minden egyes kérésnek teljesnek kell lennie önmagában. A szerver nem tárolhat kliens oldali adatokat egyik kéréstől a másikig. Minden kérésnek tartalmaznia kell minden szükséges információt (pl. hitelesítési adatok, kliens állapot), hogy a szerver megfelelően válaszolhasson.

3. HTTP protokoll használata

A REST API-k az HTTP-t használják, és kihasználják az HTTP-szabvány által biztosított metódusokat, például:

• GET: Adatok lekérdezésére használjuk.
• POST: Új erőforrás létrehozására.
• PUT: Meglévő erőforrás frissítésére vagy felülírására.
• PATCH: Egy meglévő erőforrás részleges frissítésére.
• DELETE: Erőforrás törlésére.
• OPTIONS: Lekérdezés a szerver által támogatott műveletekről.

4. Erőforrás-alapú URL struktúra

A RESTful API-kban minden erőforráshoz egy egyedi URL társul. Az URL-eket úgy kell megtervezni, hogy könnyen érthetők és logikailag szervezettek legyenek. Például:

• GET /contacts: Az összes névjegy lekérdezése.
• GET /contacts/1: Az 1-es azonosítójú névjegy lekérdezése.
• POST /contacts: Új névjegy létrehozása.
• PUT /contacts/1: Az 1-es névjegy frissítése.
• DELETE /contacts/1: Az 1-es névjegy törlése.

Az URL-eknek az erőforrásokra kell utalniuk (pl. contacts, users, orders), és azonosítókkal lehet konkrét erőforrásokra hivatkozni.

5. Állapotkódok használata

A RESTful API-k használják a HTTP válaszokban megadott állapotkódokat annak jelzésére, hogy egy kérés sikeres volt-e, vagy hibába ütközött. Példák:

• 200 OK: Sikeres kérés.
• 201 Created: Erőforrás sikeresen létrehozva (pl. új felhasználó hozzáadása).
• 400 Bad Request: Rosszul formázott kérés.
• 401 Unauthorized: Jogosultság hiánya a kéréshez.
• 403 Forbidden: Tiltott hozzáférés.
• 404 Not Found: Erőforrás nem található.
• 500 Internal Server Error: Szerveroldali hiba.

6. HATEOAS (Hypermedia as the Engine of Application State)

A RESTful API ideális esetben követi a HATEOAS elvet, ami azt jelenti, hogy a válaszok tartalmaznak további hivatkozásokat más releváns erőforrásokra. Például egy felhasználó lekérdezésére adott válasz tartalmazhat hivatkozásokat a felhasználó névjegyeire vagy rendeléseire:

{

    "id": 1,

    "name": "John Doe",

    "links": [

        { "rel": "self", "href": "/users/1" },

        { "rel": "contacts", "href": "/users/1/contacts" }

    ]

}

7. JSON használata (vagy más formátum)

A RESTful API-k általában JSON formátumban adnak vissza adatokat, mivel ez egy könnyen olvasható és platformfüggetlen formátum. Azonban XML, YAML vagy más formátumok is használhatók, attól függően, hogy mi szükséges az alkalmazás szempontjából. A válaszok JSON formátuma például:

{

    "id": 1,

    "name": "John Doe",

    "email": "john.doe@example.com"

}

8. Biztonság (HTTPS, Hitelesítés)

A RESTful API-k védelméhez HTTPS használata szükséges az adatok titkosítása érdekében. Az API-k hozzáféréséhez szükség lehet hitelesítésre, amelyet különféle módszerekkel lehet megvalósítani, például:

• OAuth: Token-alapú hitelesítés.
• API kulcsok: Minden kérésnél egy kulcs átadása, amely hitelesíti a klienst.
• JWT (JSON Web Token): Kriptografikusan aláírt token, amely tartalmazza a felhasználó adatait.

9. Cache-elhetőség

A RESTful API-kban a válaszok cache-elhetők, ha az erőforrások nem változnak gyakran. A megfelelő HTTP cache fejlécek használata biztosítja, hogy a kliens (pl. böngésző) helyi gyorsítótárából használhatja az adatokat, ami javítja a teljesítményt és csökkenti a szerver terhelését. Például a Cache-Control fejléc:

Cache-Control: max-age=3600

10. Verziózás

Az API-k folyamatos fejlesztése miatt fontos az API-k verziózása, hogy az új fejlesztések ne törjék meg a régi implementációkat. Ez többféleképpen valósítható meg, például az URL-ben:

/v1/contacts

/v2/contacts

11. Idempotencia

A RESTful API-kban az idempotens műveletek olyan műveletek, amelyek többszöri végrehajtása ugyanazt az eredményt adja. Például a GET és DELETE műveletek idempotensek, mert bármennyiszer hajtjuk végre őket, ugyanaz lesz az eredmény.

Összegzés

Egy REST API-nak tehát a következő elveket kell követnie:

1. Kliens-szerver architektúra.
2. Állapotmentesség (stateless).
3. HTTP metódusok használata (GET, POST, PUT, DELETE, stb.).
4. Erőforrás-alapú URL-ek.
5. Megfelelő állapotkódok használata.
6. HATEOAS támogatás (opcionális, de ajánlott).
7. JSON vagy más formátumú válaszok.
8. Biztonság és hitelesítés (HTTPS, OAuth, API kulcsok stb.).
9. Cache-elhetőség a megfelelő HTTP fejlécekkel.
10. Verziózás.
11. Idempotencia a megfelelő műveleteknél.

Ha egy alkalmazás megfelel ezeknek a követelményeknek, akkor REST API-nak tekinthető.