12.3 REST API izstrāde

Tavs šīs stundas izaicinājums: Saprast REST principus un izveidot pareizi strukturētu API spēļu rezultātu pārvaldībai.

SR 2.4.11. Lieto standartizētas bibliotēkas un API SR 2.4.7. Lietotāja saskarne

Teorija: REST principi

REST (Representational State Transfer) ir API projektēšanas stils, kas nosaka:

Resursu identificēšana caur URL (piem., /api/speletaji/42).
Standarta HTTP metodes ar konkrētu nozīmi (GET = lasīt, POST = izveidot, PUT = atjaunināt, DELETE = dzēst).
Stateless — katrs pieprasījums saturs visu vajadzīgo info; serveris nesaglabā stāvokli starp pieprasījumiem.
JSON kā datu formāts.

Metode	URL	Darbība
GET	/api/speletaji	Saraksts ar visiem
GET	/api/speletaji/42	Viens pēc ID
POST	/api/speletaji	Izveidot jaunu
PUT	/api/speletaji/42	Aizstāt visu
PATCH	/api/speletaji/42	Daļēji atjaunināt
DELETE	/api/speletaji/42	Dzēst

Pareizie statusa kodi: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Server Error.

1. uzdevums: Pilnvērtīga CRUD API

Pievieno visas 5 standartmaršrutas spēļu rezultātiem.

Izpildes soļi:

Izveido app.py ar globālu sarakstu REZULTATI.
GET /api/rezultati — visu sarakstu.
GET /api/rezultati/<id> — viens vai 404.
POST /api/rezultati — izveido jaunu (201).
PUT /api/rezultati/<id> — aizstāj.
DELETE /api/rezultati/<id> — dzēš (204 No Content).

2. uzdevums: Filtri un kārtošana

Pievieno query parametrus.

Izpildes soļi:

GET /api/rezultati?limit=10 — TOP 10 pēc punktiem.
GET /api/rezultati?spele=quiz — tikai "quiz" spēles rezultāti.
GET /api/rezultati?kartot=datums — pēc datuma.
Implementē, lasot request.args.get("limit", default=100, type=int).

3. uzdevums: Validācija un kļūdu apstrāde

Pārliecinies, ka API nevar "saplēst".

Izpildes soļi:

POST: validē vards nav tukšs un punkti >= 0; atgriež 400 ar specifisku kļūdas tekstu.
Visiem maršrutiem pievieno try/except: ja kļūda, atgriež 500 ar paziņojumu.
Pievieno globālu kļūdu apstrādātāju @app.errorhandler(404), kas atgriež JSON, ne HTML.
Testē ar curl, sūtot nederīgus datus.
Sadali kodu moduļos: app.py, models.py, validators.py.

Papildus uzdevums: OpenAPI dokumentācija

Automātiskā API dokumentācija.

Izpildes soļi:

pip install flask-smorest
Pievieno automātisku Swagger UI savai API.
Atver http://localhost:5000/swagger-ui un izpēti dokumentāciju.

Biežākās kļūdas

POST izmanto GET datus: JSON sūta caur body, ne URL parametriem. Dažādi request.json vs request.args.
200 OK pat kļūdām: Atgriez pareizu statusa kodu — 4xx klienta kļūdām, 5xx servera kļūdām.
API atgriež HTML kļūdas: Noklusējuma Flask 404 ir HTML — pārraksti to, lai vienmēr būtu JSON.

Koda piemērs

from flask import Flask, jsonify, request, abort

app = Flask(__name__)
REZULTATI = []

@app.route("/api/rezultati", methods=["GET"])
def saraksts():
    limit = request.args.get("limit", 100, type=int)
    sakartoti = sorted(REZULTATI, key=lambda r: r["punkti"], reverse=True)
    return jsonify(sakartoti[:limit])

@app.route("/api/rezultati", methods=["POST"])
def jauns():
    d = request.json or {}
    if not d.get("vards"): return jsonify({"kluda": "Trūkst vārds"}), 400
    if d.get("punkti", 0) < 0: return jsonify({"kluda": "Negatīvi punkti"}), 400
    d["id"] = len(REZULTATI) + 1
    REZULTATI.append(d)
    return jsonify(d), 201

@app.errorhandler(404)
def not_found(e):
    return jsonify({"kluda": "Nav atrasts"}), 404

POST → 201 Created
GET ?limit=5 → top 5
404 → {kluda: 'Nav atrasts'}