Cum să construiești un REST API: design, securitate și publicare

Pentru a construi un REST API, fă o listă cu resursele pe care le gestionează aplicația ta (utilizatori, comenzi, rezervări), dă fiecăreia un URL, de exemplu /orders și /orders/{id}, și folosește metodele HTTP pentru acțiuni: GET pentru citire, POST pentru creare, PATCH pentru actualizare, DELETE pentru ștergere. Returnează date în JSON cu coduri de stare potrivite, validează fiecare intrare, cere autentificare și verificări de permisiuni pe fiecare înregistrare, pe server, și paginează listele. Apoi documentează endpoint-urile și publică API-ul în spatele HTTPS.

Ghidul acoperă deciziile de design, un set de rute ca exemplu, prompturi pentru un AI app builder și greșelile care duc la găuri de securitate. Dacă API-urile îți sunt noi, începe cu ce este un API.

Când ai nevoie de un REST API

• Frontend-ul tău web trebuie să salveze și să încarce date de pe un server
• O aplicație mobilă, un partener sau un instrument de automatizare are nevoie de acces la datele tale
• Alte servicii îți trimit evenimente (webhook-uri)
• Împarți munca între o echipă de frontend și una de backend

REST este cel mai comun stil, dar nu singurul. REST vs GraphQL explică când un singur endpoint de interogare flexibilă este mai potrivit.

Design întâi: resurse și rute

Scrie substantivele din aplicația ta și ce fac oamenii cu ele. Pentru o aplicație simplă de rezervări:

Acestea corespund operațiilor create, read, update și delete; vezi ce este CRUD. Convenții care merită urmate:

• Substantive la plural, fără verbe în URL-uri: /bookings, nu /getBookings.
• Imbricare doar pe un nivel atunci când clarifică proprietatea: /bookings/{id}/notes.
• Acțiunile care nu sunt CRUD pot fi sub-resurse: POST /bookings/{id}/cancel este mai clar decât un PATCH „magic”.
• Denumire consecventă a câmpurilor, de exemplu created_at peste tot.

Coduri de stare și erori

Folosește codurile HTTP standard, ca clienții să știe ce s-a întâmplat fără să parseze text:

Returnează erorile într-o structură JSON consecventă, de exemplu {"error": {"code": "slot_taken", "message": "Acest interval nu mai este disponibil."}}, și nu include niciodată urme de stivă (stack traces) sau erori de bază de date în răspunsuri.

Opțiuni și compromisuri

Pas cu pas

1. Listează resursele și rutele ca mai sus, inclusiv cine are voie să apeleze fiecare.
2. Modelează datele în baza ta de date, cu câmpurile și relațiile necesare.
3. Construiește întâi rutele de citire, apoi pe cele de creare, actualizare și ștergere.
4. Validează datele la fiecare scriere cu o bibliotecă de scheme: câmpuri obligatorii, tipuri, lungimi, valori permise. Respinge câmpurile necunoscute.
5. Adaugă autentificare, apoi autorizare pe înregistrare: încărcarea lui /bookings/42 trebuie să verifice că rezervarea 42 aparține apelantului, nu doar că cineva este autentificat.
6. Paginează fiecare listă și limitează dimensiunea paginii.
7. Limitează numărul de cereri pentru autentificare și pentru rutele costisitoare. Vezi limitarea cererilor.
8. Configurează CORS doar dacă browsere de pe alte domenii trebuie să apeleze API-ul, și listează explicit originile respective. Cum rezolvi erorile CORS explică erorile pe care le vei vedea.
9. Scrie documentație și teste pentru fiecare rută, inclusiv cazurile de eroare.
10. Publică cu secretele în variabile de mediu, HTTPS, jurnale și o verificare de stare.

Prompturi pentru AI app builder-ul tău

Schelet:

Creează un REST API pentru rezervări cu aceste rute: GET /api/health, GET /api/bookings (paginat, maximum 50 pe pagină), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Stochează datele în baza noastră de date. Validează corpurile cererilor cu o bibliotecă de scheme și respinge câmpurile necunoscute. Returnează erorile JSON ca {"error": {"code", "message"}} cu coduri de stare corecte (400, 401, 403, 404, 409). Păstrează secretele în variabile de mediu.

Securitate:

Cere autentificare pe fiecare rută de rezervări. La fiecare citire, actualizare și ștergere, verifică pe server că rezervarea aparține utilizatorului curent; returnează 404 dacă nu aparține. Nu accepta niciodată ID-uri de utilizator sau roluri din corpul cererii. Limitează POST /api/bookings la 20 pe minut pentru fiecare utilizator. Înregistrează erorile pe server, fără să returnezi urme de stivă.

Documentație:

Scrie o descriere OpenAPI a acestor rute și un README scurt cu exemple de cereri și răspunsuri pentru fiecare.

Testarea API-ului

Testează din afara frontend-ului, pentru că atacatorii o vor face:

• Fiecare rută funcționează cu date valide și returnează forma și codul documentate
• Câmpurile lipsă sau invalide returnează 400 cu un mesaj clar
• Lipsa tokenului returnează 401 pe fiecare rută protejată
• Utilizatorul A care cere înregistrarea utilizatorului B după ID primește 404 sau 403
• Listele sunt paginate; un limit foarte mare este limitat
• Creările duplicate sau conflictuale returnează 409, nu 500
• Limitele de cereri returnează 429
• Răspunsurile de eroare nu conțin urme de stivă, SQL sau secrete
• CORS permite doar originile pe care le dorești

Greșeli frecvente

• Verifici autentificarea, dar nu și proprietatea. Cea mai comună gaură din API-uri: orice utilizator autentificat poate citi orice înregistrare schimbând ID-ul.
• Ai încredere în client. Prețurile, rolurile și ID-urile utilizatorilor din corpul cererii pot fi modificate.
• Returnezi rânduri întregi din baza de date. Hash-urile parolelor și câmpurile interne se scurg. Alege ce include fiecare răspuns.
• Liste fără limită. O singură cerere pentru fiecare înregistrare poate încetini întreaga aplicație.
• 200 OK cu o eroare în interior. Clienții și monitorizarea nu pot spune că a eșuat.
• CORS setat să permită orice pe un API care folosește cookie-uri.
• Fără verificare de stare sau jurnale, astfel încât afli despre întreruperi de la utilizatori.

Pentru o verificare mai amplă înainte de lansare, vezi lista de verificare de securitate pentru aplicațiile construite cu AI.

Cum construiești un REST API în Mythex

Poți cere în Mythex un API ca parte a aplicației tale sau ca serviciu separat. Rețeta din documentația REST API backend are un prompt de pornire: numești framework-ul și rutele, ceri erori JSON clare, păstrezi secretele în variabile de mediu și incluzi un Dockerfile. Backend-urile containerizate în Node, Python, C#, Java și altele se publică printr-un Dockerfile, iar Mythex se ocupă de publicare din meniul Publish (backend-uri API). Un proiect poate rula un site web și un server API alături, iar poți comuta între ele în previzualizare. Păstrează cheile ca secrete ale proiectului și, dacă API-ul are nevoie de o bază de date, cere-o în chat. Pentru lucrul programat în jurul API-ului tău, vezi cum rulezi joburi în fundal.

Întrebări