Si të ndërtoni një REST API: dizajni, siguria dhe publikimi

Për të ndërtuar një REST API, listoni burimet që menaxhon aplikacioni juaj (përdoruesit, porositë, rezervimet), jepni secilit një URL si /orders dhe /orders/{id}, dhe përdorni metodat HTTP për veprimet: GET për lexim, POST për krijim, PATCH për përditësim, DELETE për fshirje. Ktheni JSON me kode statusi të qarta, validoni çdo input, kërkoni autentikim dhe kontrolle leje për çdo regjistrim në server, dhe faqosni listat. Pastaj dokumentoni endpoint-et dhe vendoseni API-n prapa HTTPS.

Ky udhëzues mbulon vendimet e dizajnit, një grup rrugësh të punuara, prompt-e për një ndërtues aplikacionesh me AI, dhe gabimet që shkaktojnë vrima sigurie. Nëse API-t janë të reja për ju, filloni me çfarë është një API.

Kur ju duhet një REST API

• Frontend-i juaj web duhet të ruajë dhe të lexojë të dhëna nga një server
• Një aplikacion mobil, partner ose mjet automatizimi ka nevojë për akses në të dhënat tuaja
• Shërbime të tjera ju dërgojnë ngjarje (webhooks)
• Punën e ndani mes një ekipi frontend dhe një ekipi backend

REST është stili më i zakonshëm, por jo i vetmi. REST vs GraphQL shpjegon kur një endpoint i vetëm fleksibël për query përshtatet më mirë.

Dizajni i parë: burimet dhe rrugët

Shkruani emrat e aplikacionit tuaj dhe çfarë bëjnë njerëzit me ta. Për një aplikacion të thjeshtë rezervimesh:

Këto korrespondojnë me krijim, lexim, përditësim dhe fshirje; shih çfarë është CRUD. Konventa që vlen të ndiqen:

• Emra në shumës, pa folje në URL: /bookings, jo /getBookings.
• Futni vetëm një nivel kur qartëson pronësinë: /bookings/{id}/notes.
• Veprimet që nuk janë CRUD mund të jenë nënburime: POST /bookings/{id}/cancel është më e qartë se një PATCH magjik.
• Emërtim i qëndrueshëm për fushat, si created_at kudo.

Kodet e statusit dhe gabimet

Përdorni kodet standarde HTTP, që klientët të dinë çfarë ndodhi pa analizuar tekst:

Kthejini gabimet në një formë të vetme, të qëndrueshme JSON, për shembull {"error": {"code": "slot_taken", "message": "Ai orar nuk është më i disponueshëm."}}, dhe mos përfshini kurrë stack trace ose gabime të bazës së të dhënave në përgjigje.

Opsionet dhe kompromiset

Hap pas hapi

1. Listoni burimet dhe rrugët siç u tregua më sipër, duke përfshirë kush mund ta thërrasë secilën.
2. Modeloni të dhënat në bazën tuaj me fushat dhe lidhjet që ju nevojiten.
3. Ndërtoni fillimisht rrugët e leximit, pastaj krijimin, përditësimin dhe fshirjen.
4. Validoni inputin në çdo shkrim me një bibliotekë skemash: fusha të detyrueshme, tipet, gjatësitë, vlerat e lejuara. Refuzoni fushat e panjohura.
5. Shtoni autentikimin, pastaj autorizimin për çdo regjistrim: ngarkimi i /bookings/42 duhet të kontrollojë që rezervimi 42 i përket thirrësit, jo vetëm që dikush është i kyçur.
6. Faqosni çdo listë dhe kufizoni madhësinë e faqes.
7. Kufizoni kërkesat për hyrjen dhe rrugët e kushtueshme. Shih kufizimin e kërkesave.
8. Konfiguroni CORS vetëm nëse shfletuesit në domene të tjera duhet ta thërrasin API-n, dhe listoni ato origjina në mënyrë eksplicite. Si të rregulloni gabimet CORS shpjegon gabimet që do të shihni.
9. Shkruani dokumentacion dhe teste për çdo rrugë, përfshirë rastet e dështimit.
10. Publikoni me sekretet në variabla mjedisi, HTTPS, regjistra dhe një kontroll shëndeti.

Prompt-et për ndërtuesin tuaj me AI

Skela:

Krijo një REST API për rezervimet me këto rrugë: GET /api/health, GET /api/bookings (të faqosura, maks. 50 për faqe), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Ruaj të dhënat në bazën tonë. Valido trupat e kërkesave me një bibliotekë skemash dhe refuzo fushat e panjohura. Ktheji gabimet si JSON {"error": {"code", "message"}} me kodet e duhura (400, 401, 403, 404, 409). Mbaji sekretet në variabla mjedisi.

Siguria:

Kërko kyçje për çdo rrugë rezervimesh. Në çdo lexim, përditësim dhe fshirje, kontrollo në server që rezervimi i përket përdoruesit aktual; kthe 404 nëse jo. Mos prano kurrë ID-të e përdoruesve ose rolet nga trupi i kërkesës. Kufizo POST /api/bookings në 20 për minutë për përdorues. Regjistro gabimet në server pa kthyer stack trace.

Dokumentacioni:

Shkruaj një përshkrim OpenAPI për këto rrugë, dhe një README të shkurtër me shembuj kërkesash dhe përgjigjesh për secilën.

Testimi i API-t tuaj

Testojeni nga jashtë frontend-it, sepse sulmuesit do ta bëjnë:

• Çdo rrugë funksionon me input të vlefshëm dhe kthen formën dhe kodin e dokumentuar
• Fushat që mungojnë ose janë të pavlefshme kthejnë 400 me mesazh të qartë
• Pa token, çdo rrugë e mbrojtur kthen 401
• Përdoruesi A që kërkon regjistrimin e përdoruesit B me ID merr 404 ose 403
• Listat janë të faqosura; një limit shumë i madh kufizohet
• Krijimet e dyfishta ose në konflikt kthejnë 409, jo 500
• Kufijtë e kërkesave kthejnë 429
• Përgjigjet e gabimit nuk përmbajnë stack trace, SQL ose sekrete
• CORS lejon vetëm origjinat që keni ndërmend

Gabimet më të zakonshme

• Kontrollimi i kyçjes, por jo i pronësisë. Vrima më e zakonshme e API-ve: çdo përdorues i kyçur mund të lexojë çdo regjistrim duke ndryshuar ID-në.
• Besimi tek klienti. Çmimet, rolet dhe ID-të e përdoruesve nga trupi i kërkesës mund të ndryshohen.
• Kthimi i rreshtave të plotë të bazës. Hash-et e fjalëkalimeve dhe fushat e brendshme rrjedhin. Zgjidhni çfarë përfshin çdo përgjigje.
• Lista pa kufi. Një kërkesë për çdo regjistrim mund ta ngadalësojë të gjithë aplikacionin.
• 200 OK me gabim brenda. Klientët dhe monitorimi nuk mund ta dallojnë që dështoi.
• CORS i hapur për të gjithë në një API që përdor cookie.
• Pa kontroll shëndeti ose regjistra, kështu që ndërprerjet i zbuloni nga përdoruesit.

Për një kontroll më të gjerë para lançimit, shih listën e kontrollit të sigurisë për aplikacionet e ndërtuara me AI.

Ndërtimi i një REST API-je në Mythex

Në Mythex mund ta kërkoni një API si pjesë të aplikacionit tuaj ose si shërbim i veçantë. Receta e dokumentacionit REST API backend ka një prompt fillestar: emërtoni kornizën dhe rrugët, kërkoni gabime JSON të qarta, mbani sekretet në variabla mjedisi dhe përfshini një Dockerfile. Backend-et me container në Node, Python, C#, Java dhe të tjera publikohen me një Dockerfile, dhe Mythex e menaxhon publikimin nga Publish (backend-et API). Një projekt mund të ketë njëkohësisht një faqe web dhe një server API, dhe mund të ndërroni mes tyre në pamjen paraprake. Ruajini çelësat si sekrete të projektit, dhe nëse API-ja ka nevojë për bazë të dhënash, kërkojeni në chat. Për punë të planifikuara rreth API-së, shih si të ekzekutoni punë në sfond.

Pyetje