Hvernig á að smíða REST API: hönnun, öryggi og birting

Til að smíða REST API skaltu skrá auðlindirnar sem appið þitt heldur utan um (notendur, pantanir, bókanir), gefa hverri þeirra slóð eins og /orders og /orders/{id}, og nota HTTP-aðferðir fyrir aðgerðir: GET til að lesa, POST til að búa til, PATCH til að uppfæra og DELETE til að eyða. Skilaðu JSON með skýrum stöðukóðum, staðfestu sérhvert innslag, krefstu auðkenningar og athugana á heimildum fyrir hverja færslu á þjóninum, og settu upp síðuskiptingu fyrir lista. Skráðu síðan endapunktana og birtu API-ið á bak við HTTPS.

Þessi leiðarvísir fjallar um hönnunarákvarðanirnar, dæmi um slóðir, forskriftir fyrir gervigreindar-smíðatól og villurnar sem valda öryggisgötum. Ef API eru ný fyrir þér skaltu byrja á hvað API er.

Hvenær þú þarft REST API

• Vefviðmótið þitt þarf að vista og sækja gögn af þjóni
• Farsímaforrit, samstarfsaðili eða sjálfvirkt verkfæri þarf aðgang að gögnunum þínum
• Aðrar þjónustur senda þér atburði (webhooks)
• Þú ert að skipta vinnunni á milli framenda- og bakendateymis

REST er algengasti stíllinn, en ekki sá eini. REST vs GraphQL útskýrir hvenær ein sveigjanleg fyrirspurnarleið hentar betur.

Hönnun fyrst: auðlindir og slóðir

Skrifaðu niður nafnorðin í appinu þínu og hvað fólk gerir við þau. Fyrir einfalt bókunarapp:

Þessi falla að því að búa til, lesa, uppfæra og eyða; sjá hvað CRUD er. Venjur sem vert er að fylgja:

• Fleirtölu nafnorð, engar sagnir í slóðum: /bookings, ekki /getBookings.
• Hreiðra aðeins eitt stig þegar það skýrir eignarhald: /bookings/{id}/notes.
• Aðgerðir sem eru ekki CRUD geta verið undirauðlindir: POST /bookings/{id}/cancel er skýrara en töfrandi PATCH.
• Samræmd nöfn á reitum, til dæmis created_at alls staðar.

Stöðukóðar og villur

Notaðu staðlaða HTTP-kóða svo að viðskiptavinir viti hvað gerðist án þess að lesa texta:

Skilaðu villum í einu samræmdu JSON-formi, til dæmis {"error": {"code": "slot_taken", "message": "Þessi tími er ekki lengur laus."}}, og hafðu aldrei stack trace eða gagnagrunnsvillur í svörum.

Valkostir og málamiðlanir

Skref fyrir skref

1. Skráðu auðlindir og slóðir eins og að ofan, þar á meðal hver má kalla á hverja.
2. Móttu gögnin í gagnagrunninum þínum með þeim reitum og tengslum sem þú þarft.
3. Smíðaðu leslesturleiðir fyrst, síðan búa til, uppfæra og eyða.
4. Staðfestu innslag í hverri skrifaðgerð með skemaasafni: nauðsynlegir reitir, gerðir, lengdir, leyfð gildi. Hafnaðu óþekktum reitum.
5. Bættu við auðkenningu, og síðan heimildastýringu fyrir hverja færslu: að opna /bookings/42 verður að athuga að bókun 42 tilheyri notandanum, ekki bara að einhver sé innskráður.
6. Settu síðuskiptingu á alla lista og takmarkaðu stærð síðu.
7. Takmarkaðu fjölda beiðna á innskráningu og dýrar leiðir. Sjá hraðatakmarkanir.
8. Stilltu CORS aðeins ef vafrar á öðrum lénum þurfa að kalla á API-ið, og skráðu þau upprunalén sérstaklega. Hvernig lagar maður CORS-villur útskýrir villurnar sem þú sérð.
9. Skrifaðu skjöl og próf fyrir hverja leið, þar á meðal tilvikin sem mistakast.
10. Birtu með leyndarmálum í umhverfisbreytum, HTTPS, skráningu og heilsuathugun.

Forskriftir fyrir gervigreindar-smíðatólið þitt

Grind:

Búðu til REST API fyrir bókanir með þessum leiðum: GET /api/health, GET /api/bookings (með síðuskiptingu, hámark 50 á síðu), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Geymdu gögnin í gagnagrunninum okkar. Staðfestu beiðnabúka með skemasafni og hafnaðu óþekktum reitum. Skilaðu JSON-villum sem {"error": {"code", "message"}} með réttum stöðukóðum (400, 401, 403, 404, 409). Geymdu leyndarmál í umhverfisbreytum.

Öryggi:

Krefstu innskráningar á öllum bókunarleiðum. Við hverja lestur, uppfærslu og eyðingu skaltu athuga á þjóninum að bókunin tilheyri núverandi notanda; skila 404 ef ekki. Taktu aldrei við notendaauðkennum eða hlutverkum úr beiðnabúkinu. Takmarkaðu POST /api/bookings við 20 á mínútu á hvern notanda. Skráðu villur á þjóninum án þess að skila stack trace.

Skjöl:

Skrifaðu OpenAPI-lýsingu á þessum leiðum og stutt README með dæmum um beiðnir og svör fyrir hverja leið.

Prófun á API-inu þínu

Prófaðu utan framendans, því árásaraðilar gera það:

• Hver leið virkar með réttu innslagi og skilar skráðu formi og kóða
• Vantar eða ógild reitir skila 400 með skýrum skilaboðum
• Ekkert auðkenni skilar 401 á öllum vernduðum leiðum
• Notandi A sem biður um færslu notanda B eftir auðkenni fær 404 eða 403
• Listar eru með síðuskiptingu; of stór limit er takmarkaður
• Afrit eða stangast á við stofnun skila 409, ekki 500
• Hraðatakmarkanir skila 429
• Villusvör innihalda engin stack trace, SQL eða leyndarmál
• CORS leyfir aðeins þau upprunalén sem þú ætlar

Algeng mistök

• Athuga innskráningu en ekki eignarhald. Algengasta API-gatið: hver innskráður notandi getur lesið hvaða færslu sem er með því að breyta auðkenninu.
• Treysta viðskiptavininum. Verð, hlutverk og notendaauðkenni úr beiðnabúknum er hægt að breyta.
• Skila heilum gagnagrunnsröðum. Lykilorðsvöfflur og innri reitir leka. Veldu hvað hvert svar inniheldur.
• Ótakmarkaðir listar. Ein beiðni fyrir allar færslur getur hægt á allt appið.
• 200 OK með villuskilaboðum inni í. Viðskiptavinir og eftirlit sjá ekki að það mistókst.
• CORS stillt á að leyfa allt á API sem notar setukökur.
• Engin heilsuathugun eða skráning, þannig að þú frétt af truflunum frá notendum.

Fyrir víðtækari yfirferð fyrir opnun, sjá öryggisgátlistann fyrir forrit smíðuð með gervigreind.

Að smíða REST API í Mythex

Þú getur beðið Mythex um API sem hluta af appinu þínu eða sem sérstaka þjónustu. Skjalauppskriftin REST API backend hefur upphafsforskrift: nefndu rammann og leiðirnar, biddu um skýrar JSON-villur, geymdu leyndarmál í umhverfisbreytum og hafðu Dockerfile með. Gámabakendar í Node, Python, C#, Java og fleiri birtast í gegnum Dockerfile, og Mythex sér um birtinguna úr Publish (API backends). Verkefni getur keyrt vefsíðu og API-þjón hlið við hlið, og þú getur skipt á milli þeirra í forskoðuninni. Geymdu lykla sem verkefnisleyndarmál, og ef API-ið þarf gagnagrunn skaltu biðja um hann í spjallinu. Fyrir tímasett verk í kringum API-ið, sjá hvernig keyrir maður bakgrunnsverk.

Spurningar