Ինչպես ստեղծել REST API. դիզայն, անվտանգություն և տեղակայում

REST API ստեղծելու համար թվարկեք այն ռեսուրսները, որոնք կառավարում է ձեր հավելվածը (օգտատերեր, պատվերներ, ամրագրումներ), յուրաքանչյուրին տվեք URL, ինչպիսին է /orders-ը և /orders/{id}-ը, և գործողությունների համար օգտագործեք HTTP մեթոդներ՝ GET կարդալու, POST՝ ստեղծելու, PATCH՝ թարմացնելու, DELETE՝ հեռացնելու համար։ Վերադարձրեք JSON իմաստալից կարգավիճակի կոդերով, վավերացրեք յուրաքանչյուր մուտքագրում, պահանջեք նույնականացում և սերվերի վրա յուրաքանչյուր գրառման թույլտվության ստուգում, էջավորեք ցանկերը։ Ապա փաստաթղթավորեք վերջնակետերը և տեղակայեք API-ը HTTPS-ի հետևում։

Այս ուղեցույցը ընդգրկում է դիզայնի որոշումները, աշխատող երթուղիների հավաքածու, հրահանգներ AI հավելվածի կառուցողի համար և այն սխալները, որոնք հանգեցնում են անվտանգության անցքերի։ Եթե API-ները ձեզ նոր են, սկսեք ինչ է API-ն էջից։

Երբ ձեզ անհրաժեշտ է REST API

Ձեր վեբ ինտերֆեյսը պետք է պահի և բեռնի տվյալներ սերվերից
Բջջային հավելվածը, գործընկերը կամ ավտոմատացման գործիքը պետք է մուտք ունենա ձեր տվյալներին
Այլ ծառայություններ ուղարկում են ձեզ իրադարձություններ (webhook-ներ)
Դուք աշխատանքը բաժանում եք ճակատային և հետին թիմերի միջև

REST-ը ամենատարածված ոճն է, բայց ոչ միակը։ REST vs GraphQL բացատրում է, թե երբ ավելի հարմար է մեկ ճկուն հարցման վերջնակետը։

Նախ դիզայն. ռեսուրսներ և երթուղիներ

Ձեր հավելվածի գոյականները և մարդիկ դրանց հետ ինչ են անում գրեք։ Պարզ ամրագրման հավելվածի համար՝

Մեթոդ	Երթուղի	Ինչ է անում	Հաջողության կոդ
`GET`	`/api/bookings`	Ցույց է տալիս կանչողի ամրագրումները (էջավորված)	200
`POST`	`/api/bookings`	Ստեղծում է ամրագրում	201
`GET`	`/api/bookings/{id}`	Ստանում է մեկ ամրագրում	200
`PATCH`	`/api/bookings/{id}`	Փոխում է որոշ դաշտեր	200
`DELETE`	`/api/bookings/{id}`	Չեղարկում է ամրագրումը	204
`GET`	`/api/health`	Առողջության ստուգում մոնիթորինգի համար	200

SՍրանք համապատասխանում են ստեղծման, կարդալու, թարմացման և հեռացման գործողություններին. տես ինչ է CRUD-ը։ Արժե հետևել հետևյալ կոնվենցիաներին.

Հոգնակի գոյականներ, առանց բայերի URL-ներում՝ /bookings, ոչ թե /getBookings։
Տեղադրեք միայն մեկ մակարդակ, երբ դա պարզում է պատկանելիությունը՝ /bookings/{id}/notes։
Ոչ CRUD գործողությունները կարող են լինել ենթառեսուրսներ՝ POST /bookings/{id}/cancel-ը ավելի պարզ է, քան կախարդական PATCH-ը։
Հետևողական անվանում դաշտերի համար, օրինակ՝ created_at ամենուր։

Կարգավիճակի կոդեր և սխալներ

Օգտագործեք ստանդարտ HTTP կոդեր, որպեսզի հաճախորդները առանց տեքստը վերլուծելու իմանան, թե ինչ եղավ.

Կոդ	Իմաստ	Օգտագործեք, երբ
200	OK	Հաջող կարդալ կամ թարմացնել
201	Created	POST-ը ինչ-որ բան ստեղծեց
204	No Content	Հաջողություն՝ առանց վերադարձվող տվյալների
400	Bad Request	Մուտքագրումը չի անցել վավերացումը
401	Unauthorized	Մուտք չկա կամ թոքենը սխալ է
403	Forbidden	Մուտք կա, բայց թույլատրված չէ
404	Not Found	Գոյություն չունի, կամ կանչողը չպետք է իմանա, որ այն գոյություն ունի
409	Conflict	Կրկնօրինակ է, կամ ժամը արդեն զբաղված է
429	Too Many Requests	Հասել է սահմանաչափին
500	Server Error	Ինչ-որ բան խափանվել է ձեր կողմից

Վերադարձրեք սխալները մեկ հետևողական JSON ձևաչափով, օրինակ՝ {"error": {"code": "slot_taken", "message": "Այդ ժամը այլևս հասանելի չէ։"}}, և երբեք մի՛ ներառեք stack trace-եր կամ տվյալների բազայի սխալներ պատասխաններում։

Տարբերակներ և փոխզիջումներ

Որոշում	Պարզ ընտրություն	Այլընտրանք
Որտեղ է գտնվում API-ն	API երթուղիներ ձեր վեբ շրջանակում	Առանձին API ծառայություն, օգտակար մի քանի հաճախորդների կամ այլ լեզվի դեպքում
Նույնականացում	Session cookie-ներ ձեր սեփական վեբ հավելվածի համար	Թոքեններ (bearer թոքեններ կամ API բանալիներ) բջջային հավելվածների և երրորդ կողմերի համար
Էջավորում	`?page=2&limit=20`	Cursor-ով (`?after=...`), ավելի կայուն մեծ, փոփոխվող ցուցակների համար
Տարբերակավորում	Չկա, մինչև արտաքին օգտատերեր ունենաք	`/v1/` ուղու մեջ, երբ ուրիշներն արդեն կախված են դրանից
Փաստաթղթեր	README՝ երթուղիների ցանկով	OpenAPI սպեցիֆիկացիա, որից գործիքները կարող են ստեղծել ինտերակտիվ փաստաթղթեր և հաճախորդի կոդ

Քայլ առ քայլ

Թվարկեք ռեսուրսներն ու երթուղիները ինչպես վերևում, ներառյալ՝ ով կարող է կանչել յուրաքանչյուրը։
Մոդելավորեք տվյալները ձեր տվյալների բազայում՝ անհրաժեշտ դաշտերով և կապերով։
Նախ կառուցեք կարդալու երթուղիները, հետո ստեղծելու, թարմացնելու և հեռացնելու։
Վավերացրեք մուտքագրումը յուրաքանչյուր գրելու գործողության ժամանակ սխեմայի գրադարանով. պարտադիր դաշտեր, տիպեր, երկարություններ, թույլատրված արժեքներ։ Մերժեք անհայտ դաշտերը։
Ավելացրեք նույնականացում, ապա գրառման առ գրառում թույլտվություն. /bookings/42-ը բեռնելիս պետք է ստուգվի, որ ամրագրում 42-ը պատկանում է կանչողին, և ոչ միայն այն, որ ինչ-որ մեկը մուտք է գործել։
Էջավորեք յուրաքանչյուր ցուցակ և սահմանեք էջի առավելագույն չափը։
Սահմանափակեք հարցումները մուտքի և թանկարժեք երթուղիների համար։ Տես հարցումների սահմանափակում։
Կարգավորեք CORS-ը միայն այն դեպքում, երբ այլ դոմեյնների բրաուզերները պետք է կանչեն API-ն, և այդ ծագումները թվարկեք հստակ։ Ինչպես ուղղել CORS սխալները բացատրում է, թե ինչ սխալներ կտեսնեք։
Գրեք փաստաթղթեր և թեստեր յուրաքանչյուր երթուղու համար, ներառյալ ձախողման դեպքերը։
Տեղակայեք գաղտնի տվյալները միջավայրի փոփոխականներում, HTTPS-ով, լոգերով և առողջության ստուգմամբ։

Հրահանգներ ձեր AI կառուցողին

Սկաֆոլդ.

Ստեղծիր REST API ամրագրումների համար այս երթուղիներով. GET /api/health, GET /api/bookings (էջավորված, առավելագույնը 50 էջում), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Տվյալները պահիր մեր տվյալների բազայում։ Վավերացրու հարցման մարմինը սխեմայի գրադարանով և մերժիր անհայտ դաշտերը։ Վերադարձրու JSON սխալները {"error": {"code", "message"}} ձևաչափով ճիշտ կարգավիճակի կոդերով (400, 401, 403, 404, 409)։ Գաղտնի տվյալները պահիր միջավայրի փոփոխականներում։

Անվտանգություն.

Պահանջիր մուտք յուրաքանչյուր bookings երթուղու համար։ Յուրաքանչյուր կարդալու, թարմացնելու և հեռացնելու գործողության ժամանակ ստուգիր սերվերի վրա, որ ամրագրումը պատկանում է ընթացիկ օգտատիրոջը. եթե ոչ՝ վերադարձրու 404։ Հարցման մարմնից երբեք մի ընդունիր օգտատիրոջ ID-ներ կամ դերեր։ POST /api/bookings-ի համար սահմանափակիր յուրաքանչյուր օգտատիրոջ համար՝ րոպեում 20։ Սերվերի վրա գրանցիր սխալները՝ առանց stack trace-երը վերադարձնելու։

Փաստաթղթեր.

Գրիր այս երթուղիների OpenAPI նկարագրությունը և կարճ README՝ յուրաքանչյուրի համար օրինակ հարցումներով ու պատասխաններով։

API-ի թեստավորում

Թեստավորեք դուրս ճակատային մասից, քանի որ հարձակվողները կանեն դա.

Յուրաքանչյուր երթուղի աշխատում է վավեր մուտքագրմամբ և վերադարձնում է փաստաթղթավորված կառուցվածքն ու կոդը
Բացակայող կամ անվավեր դաշտերը վերադարձնում են 400՝ հստակ հաղորդագրությամբ
Առանց թոքենի յուրաքանչյուր պաշտպանված երթուղի վերադարձնում է 401
Օգտատեր A-ն, որը պահանջում է օգտատեր B-ի գրառումը ID-ով, ստանում է 404 կամ 403
Ցուցակները էջավորված են. հսկայական limit-ը սահմանափակվում է
Կրկնօրինակ կամ հակասող ստեղծումները վերադարձնում են 409, ոչ թե 500
Սահմանաչափերը վերադարձնում են 429
Սխալի պատասխանները չեն պարունակում stack trace-եր, SQL կամ գաղտնի տվյալներ
CORS-ը թույլ է տալիս միայն այն ծագումները, որոնք նախատեսել եք

Սովորական սխալներ

Մուտքը ստուգվում է, բայց սեփականատերը՝ ոչ։ Ամենատարածված API անցքը. ցանկացած մուտք գործած օգտատեր կարող է կարդալ ցանկացած գրառում՝ փոխելով ID-ը։
Հաճախորդին վստահելը։ Գները, դերերը և օգտատերերի ID-ները հարցման մարմնից կարող են փոփոխվել։
Ամբողջական տվյալների բազայի տողերի վերադարձ։ Գաղտնաբառի հեշերը և ներքին դաշտերը արտահոսում են։ Ընտրեք, թե ինչ պետք է ներառի յուրաքանչյուր պատասխան։
Անսահման ցուցակներ։ Մեկ հարցումը բոլոր գրառումների համար կարող է դանդաղեցնել ամբողջ հավելվածը։
200 OK ներսում սխալ հաղորդագրությամբ։ Հաճախորդները և մոնիթորինգը չեն կարող հասկանալ, որ ձախողում է եղել։
CORS-ը սահմանված է թույլատրել ամեն ինչ cookie-ներ օգտագործող API-ի վրա։
Չկա առողջության ստուգում կամ լոգեր, այնպես որ խափանումների մասին իմանում եք օգտատերերից։

Ավելի լայն նախահրապարակային ստուգման համար տես AI-ով կառուցված հավելվածների անվտանգության ստուգաթերթը։

REST API-ի կառուցումը Mythex-ում

Դուք կարող եք Mythex-ից խնդրել API՝ որպես ձեր հավելվածի մաս կամ որպես առանձին ծառայություն։ REST API backend փաստաթղթերի բաղադրատոմսը ունի մեկնարկային հրահանգ. նշեք ձեր շրջանակը և երթուղիները, պահանջեք հստակ JSON սխալներ, պահեք գաղտնի տվյալները միջավայրի փոփոխականներում և ներառեք Dockerfile։ Node, Python, C# և Java կոնտեյներային backend-ները տեղակայվում են Dockerfile-ի միջոցով, և Mythex-ը կատարում է տեղակայումը Publish-ից (API backends)։ Նախագիծը կարող է միաժամանակ աշխատեցնել վեբ կայք և API սերվեր, և դուք կարող եք անցնել նրանց միջև նախադիտման մեջ։ Գաղտնի տվյալները պահեք որպես նախագծի գաղտնիքներ, և եթե API-ին տվյալների բազա է պետք, խնդրեք այն չաթում։ Ձեր API-ի կողքի պլանավորված աշխատանքների համար տես ինչպես աշխատեցնել ֆոնային առաջադրանքները։

Հարցեր

Ի՞նչ է REST API-ն

REST API-ն ծրագրերին հնարավորություն է տալիս աշխատել ձեր հավելվածի տվյալների հետ HTTP-ի միջոցով։ Յուրաքանչյուր տվյալների տեսակ ռեսուրս է՝ սեփական URL-ով, օրինակ՝ /orders, և ստանդարտ մեթոդները կատարվում են նրա վրա՝ GET կարդալու, POST ստեղծելու, PATCH կամ PUT թարմացնելու և DELETE հեռացնելու համար։ Տվյալները սովորաբար փոխանցվում են JSON ձևաչափով։

Ո՞ր լեզվով պետք է ստեղծեմ REST API

Օգտագործեք այն, ինչ դուք կամ ձեր թիմը կարող եք պահպանել։ Node.js-ը Express-ով կամ Fastify-ով, Python-ը FastAPI-ով և C#-ի կամ Java-ի շրջանակները բոլորը լավ են աշխատում։ Երթուղիների, կարգավիճակի կոդերի, վավերացման և նույնականացման դիզայնի կանոնները ավելի կարևոր են, քան լեզուն։

Ինչպե՞ս պաշտպանել REST API-ը

Պահանջեք նույնականացում յուրաքանչյուր ոչ հանրային երթուղու համար, սերվերի վրա ստուգեք, որ կանչողը կարող է մուտք ունենալ յուրաքանչյուր առանձին գրառման, վավերացրեք ամբողջ մուտքագրումը, օգտագործեք HTTPS, սահմանափակեք հարցումների քանակը և գաղտնի տվյալները պահեք միջավայրի փոփոխականներում։ Երբեք մի՛ վստահեք հաճախորդի կողմից ուղարկված ID-ներին կամ դերերին։

Արդյո՞ք REST API-ի համար առանձին backend է պետք

Ոչ միշտ։ Շրջանակները, ինչպիսին է Next.js-ը, կարող են մատուցել API երթուղիներ էջերի կողքին։ Առանձին API ծառայությունն իմաստ ունի, երբ մի քանի հաճախորդ (վեբ, բջջային, գործընկերներ) օգտագործում են այն կամ երբ նրան անհրաժեշտ է սեփական լեզու կամ մասշտաբավորում։