REST API-ներ

01Ռեսուրսներ և URL-ներ

REST-ը (Representational State Transfer) ձեր domain-ը մոդելավորում է որպես ռեսուրսներ՝ գոյականներ, ինչպիսիք են products, orders և customers։ Յուրաքանչյուր ռեսուրս ունի URL, իսկ մեթոդն ասում է, թե ինչ անել դրա հետ։ Օգտագործեք հոգնակի գոյականներ և ID-ներ՝ /orders, /orders/1001, /orders/1001/items։ Խուսափեք path-երում բայերից, ինչպիսիք են /getOrders կամ /createOrder․ մեթոդն արդեն դա ասում է։ Nesting-ը պահեք մակերեսային (սովորաբար մեկ մակարդակը բավական է)։ Այն գործողությունների համար, որոնք պարզորեն չեն համապատասխանում CRUD-ին, մոդելավորեք դրանք որպես sub-resource-ներ կամ վիճակի փոփոխություններ՝ POST /orders/1001/cancellation կամ PATCH /orders/1001 status դաշտով։ Օգտագործեք հետևողական անվանում (camelCase կամ snake_case, ընտրեք մեկը), ISO 8601 ամսաթվեր UTC-ով և ID-ներ, որոնք չեն բացահայտում բիզնեսի ծավալը, որտեղ դա կարևոր է։ Անալոգիա՝ ռեսուրսները շենքի սենյակներն են, URL-ները՝ նրանց հասցեները, իսկ մեթոդները՝ այն, ինչ անում եք սենյակում։

1GET    /v1/orders?status=pending&page=2   # list
2POST   /v1/orders                         # create
3GET    /v1/orders/1001                    # read one
4PATCH  /v1/orders/1001                    # partial update
5DELETE /v1/orders/1001                    # delete
6GET    /v1/customers/77/orders            # related collection
7POST   /v1/orders/1001/refunds            # action as sub-resource

02Մեթոդներ, status code-եր և սխալի ֆորմատ

Գործողությունները համապատասխանեցրեք մեթոդներին, իսկ արդյունքները՝ status code-երին։ Ստեղծումը վերադարձնում է 201 Created՝ Location header-ով և նոր ռեսուրսով։ Առանց բովանդակության հաջողությունը վերադարձնում է 204։ Վալիդացիայի սխալները վերադարձնում են 422 (կամ 400՝ սխալ ձևավորված JSON-ի համար)՝ դաշտերի մակարդակի մանրամասներով։ Նույնականացված չէ՝ 401, թույլատրված չէ՝ 403, բացակայում է՝ 404, տարբերակի կամ վիճակի կոնֆլիկտ՝ 409, չափազանց շատ հարցումներ՝ 429, իսկ սերվերի բագերը՝ 500։ Ընտրեք սխալի մեկ ֆորմատ և օգտագործեք այն ամենուր։ RFC 9457 Problem Details-ը (application/problem+json) լավ ստանդարտ է՝ type, title, status, detail, գումարած ձեր սեփական դաշտերը, օրինակ՝ սխալներն ըստ դաշտերի և request ID՝ support-ի համար։ Production-ի սխալներում երբեք մի բացահայտեք stack trace-եր կամ SQL։

1HTTP/1.1 422 Unprocessable Content
2Content-Type: application/problem+json
3 
4{
5  "type": "https://api.example.com/problems/validation",
6  "title": "The request has invalid fields.",
7  "status": 422,
8  "errors": { "quantity": ["Must be at least 1."] },
9  "requestId": "req_7f3a9c"
10}

03Pagination, ֆիլտրում, դասավորում

Երբեք մի վերադարձրեք անսահմանափակ ցուցակներ։ Offset pagination-ը (?page=3&per_page=20) պարզ է և թույլ է տալիս օգտատերերին ցատկել էջի, բայց մեծ աղյուսակներում դանդաղում է և կարող է բաց թողնել կամ կրկնել տարրեր, երբ տվյալները փոխվում են։ Cursor pagination-ը (?cursor=eyJpZCI6MTAwMH0&limit=20) օգտագործում է անթափանց ցուցիչ, օրինակ՝ վերջին տեսած ID-ն և created_at-ը․ այն արագ և կայուն է feed-երի, infinite scroll-ի և sync-երի համար, բայց չի կարող ցատկել 50-րդ էջ։ Վերադարձրեք մետատվյալներ կամ հղումներ, որպեսզի client-ներն իրենք URL-ներ չկառուցեն։ Ֆիլտրման համար օգտագործեք հստակ query պարամետրեր (?status=paid&created_from=2026-01-01), դասավորման համար՝ ?sort=-created_at,total, իսկ որոնման համար՝ ?q=։ Սահմանափակեք էջի առավելագույն չափը և ֆիլտրումն ու դասավորումը թույլատրեք միայն index արված դաշտերով։

1GET /v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAyMH0
2 
3{
4  "data": [ { "id": 1019, "total": 12500, "status": "paid" } ],
5  "meta": { "limit": 20, "hasMore": true },
6  "links": { "next": "/v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwMH0" }
7}

04Տարբերակավորում և անվտանգ զարգացում

Client-ները, հատկապես մոբայլ հավելվածները, որոնք օգտատերերը չեն թարմացնում, տարիներ շարունակ կախված են ձեր API-ից։ Ավելացնող փոփոխություններն անվտանգ են՝ նոր endpoint-ներ, նոր ոչ պարտադիր դաշտեր, նոր enum արժեքներ, եթե client-ներին ասվել է հանդուրժել անհայտները։ Կոտրող փոփոխությունները ներառում են դաշտերի հեռացումը կամ վերանվանումը, տիպերի կամ իմաստի փոփոխությունը և ոչ պարտադիր մուտքը պարտադիր դարձնելը։ Կոտրող փոփոխությունների համար ներմուծեք նոր տարբերակ։ URL-ով տարբերակավորումը (/v1, /v2) ամենատեսանելին է և ամենահեշտը route անելու, քեշավորելու և debug անելու համար, header-ով կամ media-type-ով տարբերակավորումը URL-ները պահում է մաքուր, բայց ավելի դժվար է թեստավորել։ Որոշ API-ներ header-ում օգտագործում են ամսաթվով տարբերակներ։ Ինչ էլ ընտրեք, deprecation-ների մասին հայտարարեք ամսաթվերով, ուղարկեք Deprecation և Sunset header-ներ և հետևեք, թե որ client-ներն են դեռ կանչում հին տարբերակները, նախքան դրանք անջատելը։ Զուգակցեք սա մոբայլ հավելվածներում forced-update մեխանիզմի հետ։

05Նույնականացում, idempotency և rate limit-եր

Auth-ն ընտրեք ըստ client-ի տեսակի։ Նույն կայքի բրաուզերային հավելվածներ՝ անվտանգ HttpOnly session cookie-ներ գումարած CSRF պաշտպանություն։ Մոբայլ և SPA client-ներ՝ կարճաժամկետ access token-ներ (հաճախ JWT) refresh token-ներով, երրորդ կողմի login-ի համար՝ OAuth 2 flow-երով PKCE-ով։ Server-to-server գործընկերներ՝ սահմանափակ իրավունքներով API key-եր կամ OAuth client credentials, որոնք ուղարկվում են header-ներով, երբեք՝ URL-ներով։ Ցանցերը խափանվում են, ուստի գրելու գործողությունները դարձրեք անվտանգ կրկնելու համար․ client-ներն ուղարկում են Idempotency-Key header եզակի արժեքով, սերվերը պահում է key-ը արդյունքի հետ և key-ի կրկնության դեպքում վերադարձնում նույն պատասխանը՝ երկու անգամ գանձելու կամ պատվիրելու փոխարեն։ Պաշտպանեք API-ն rate limit-երով ըստ key-ի, օգտատիրոջ կամ IP-ի, պատասխանեք 429-ով Retry-After-ի հետ և սահմանափակումները ցույց տվեք header-ներում, որպեսզի client-ները կարողանան դանդաղեցնել։

1POST /v1/payments HTTP/1.1
2Authorization: Bearer <access_token>
3Idempotency-Key: 6f1c2d4e-8a7b-4c3d-9e2f-1a2b3c4d5e6f
4Content-Type: application/json
5 
6{"orderId": 1001, "amount": 12500, "currency": "AMD"}
7 
8HTTP/1.1 429 Too Many Requests
9Retry-After: 30
10RateLimit-Policy: "default";q=100;w=60

06Փաստաթղթավորում OpenAPI-ով

OpenAPI-ն (3.1 տարբերակն ընթացիկն է և համահունչ է JSON Schema-ին) YAML կամ JSON ֆայլում նկարագրում է ձեր endpoint-ները, պարամետրերը, հարցման և պատասխանի body-ները, սխալները և auth-ը։ Այդ մեկ աղբյուրից ստանում եք ինտերակտիվ փաստաթղթեր (Swagger UI, Redoc, Scalar), գեներացված տիպավորված client-ներ TypeScript-ի, Kotlin-ի կամ Swift-ի համար, mock սերվերներ և contract test-եր։ Գեներացրեք այն կոդի annotation-ներից կամ decorator-ներից (NestJS-ն ունի ներկառուցված աջակցություն, Laravel-ն ունի փաթեթներ, օրինակ՝ Scramble), որպեսզի այն երբեք չշեղվի իրականությունից։ Ավելացրեք օրինակներ յուրաքանչյուր հարցման և սխալի համար, նկարագրեք pagination-ը և rate limit-երը և հրապարակեք changelog։ Լավ փաստաթղթերը feature են․ դրանք ինտեգրման ժամանակը շաբաթներից կրճատում են օրերի։

1paths:
2  /v1/orders/{id}:
3    get:
4      summary: Get one order
5      parameters:
6        - { name: id, in: path, required: true, schema: { type: integer } }
7      responses:
8        "200":
9          description: The order
10          content:
11            application/json:
12              schema: { $ref: "#/components/schemas/Order" }
13        "404": { $ref: "#/components/responses/NotFound" }

07REST vs GraphQL vs gRPC vs WebSockets vs webhooks

Դրանք լուծում են տարբեր խնդիրներ և հաճախ ապրում են կողք կողքի։ REST-ը լռելյայն ընտրությունն է հանրային և մոբայլ API-ների համար՝ պարզ, քեշավորվող, հասկանալի յուրաքանչյուր գործիքի համար։ GraphQL-ը թույլ է տալիս client-ներին մեկ endpoint-ից խնդրել հենց այն դաշտերը, որոնք իրենց պետք են, ինչն օգնում է, երբ շատ տարբեր էկրաններ միավորում են տվյալներ բազմաթիվ աղբյուրներից․ գինը բարդ քեշավորումն է, authorization-ն ըստ դաշտի և query-ի արժեքի սահմանափակումները։ gRPC-ն օգտագործում է Protocol Buffers HTTP/2-ի վրա՝ գեներացված client-ներով և streaming-ով․ հիանալի է արագ, տիպավորված service-to-service կանչերի համար, անհարմար է բրաուզերներում։ WebSockets-ը բաց է պահում երկկողմանի կապ չատի, պատվերի live կարգավիճակի և dashboard-ների համար։ Webhook-ները հակադարձ API-ներ են․ ձեր սերվերը կանչում է գործընկերոջ URL-ը, երբ ինչ-որ բան է տեղի ունենում, օրինակ՝ վճարումը հաջողվել է․ ստորագրեք դրանք HMAC-ով, կրկնեք backoff-ով և ստացողներին դարձրեք idempotent։

• Հանրային, գործընկերային կամ մոբայլ API՝ REST + OpenAPI։
• Շատ client-ներ՝ տվյալների շատ տարբեր կարիքներով՝ դիտարկեք GraphQL։
• Ներքին բարձր թողունակությամբ ծառայություններ՝ gRPC։
• Live թարմացումներ օգտատերերին՝ WebSockets կամ SSE։ Իրադարձություններ այլ համակարգերին՝ webhook-ներ։

08Authorization-ը API-ի թիվ մեկ ռիսկն է

OWASP API Security Top 10-ը (2023) առաջին տեղում դնում է Broken Object Level Authorization-ը. API-ն ստուգում է, որ օգտատերը login է արել, բայց ոչ այն, որ նրա պահանջած պատվերը, հաշիվ-ապրանքագիրը կամ ֆայլը իրեն է պատկանում, ուստի /orders/1001-ը /orders/1002 փոխելը բացահայտում է ուրիշի տվյալները։ Մոտիկից հետևում են broken function-level authorization-ը (սովորական օգտատերը կանչում է ադմինի endpoint) և broken object property level authorization-ը (mass assignment, երբ client-ը PATCH body-ում սահմանում է role կամ price)։ Հուսալի pattern-ը յուրաքանչյուր query-ն կանչողով սահմանափակելն է, ոչ թե հետո ստուգելը. բեռնեք օգտատիրոջ կամ tenant-ի relationship-ի միջոցով, որպեսզի օտար ID-ն պարզապես ոչինչ չգտնի և վերադարձնի 404։ Յուրաքանչյուր endpoint-ի համար whitelist արեք գրվող դաշտերը և օգտագործեք policy-ներ կամ guard-եր, որոնք աշխատում են ամեն route-ում։ Պատահական կամ prefix-ով ID-ները դժվարացնում են գուշակելը, բայց երբեք չեն փոխարինում authorization-ին։

1// Laravel: scope by owner, then authorize with a policy
2public function show(Request $request, int $id)
3{
4    $order = $request->user()->orders()->findOrFail($id); // 404 for others
5    $this->authorize('view', $order);
6    return new OrderResource($order);
7}
8 
9// Only allow known fields to be written
10$data = $request->validate([
11    'note'     => ['nullable', 'string', 'max:500'],
12    'quantity' => ['required', 'integer', 'min:1'],
13]);

09Երկարատև գործողություններ և հուսալի իրադարձություններ

Որոշ հարցումներ չեն կարող ավարտվել սովորական timeout-ի ընթացքում. export-ներ, import-ներ, video-ի մշակում, զանգվածային թարմացումներ։ Կապը բաց պահելու փոխարեն ընդունեք աշխատանքը և վերադարձրեք 202 Accepted՝ Location header-ով, որը մատնացույց է անում status ռեսուրս, օրինակ՝ /v1/jobs/77։ Client-ը polling է անում այդ ռեսուրսը կամ բաժանորդագրվում webhook-ի, և վերջում անցնում է արդյունքի հղումով։ Հարակից խնդիր է իրադարձությունների հուսալի հրապարակումը։ Եթե կոդը պահպանում է պատվերը, հետո ուղարկում webhook, երկու քայլերի միջև crash-ը կորցնում է իրադարձությունը. նախ ուղարկելը, հետո պահպանման ձախողումը ստեղծում է «ուրվական» իրադարձություն։ Transactional outbox pattern-ը սա լուծում է. պատվերը և outbox տողը գրեք նույն database transaction-ում, և թողեք, որ worker-ը outbox տողերը առաքի retry-ներով։ Consumer-ները դեռ պետք է deduplicate անեն ըստ event ID-ի, քանի որ առաքումը at least once է։

1POST /v1/exports HTTP/1.1
2Content-Type: application/json
3 
4{"type": "orders", "from": "2026-10-01", "to": "2026-10-31"}
5 
6HTTP/1.1 202 Accepted
7Location: /v1/jobs/77
8 
9GET /v1/jobs/77  ->  {"status": "running", "progress": 40}
10GET /v1/jobs/77  ->  {"status": "done", "resultUrl": "/v1/exports/77/file"}

10Rate limiting-ի ալգորիթմներ

Fixed window-ը հաշվում է հարցումները ըստ օրացուցային րոպեի. պարզ է, բայց սահմանին թույլ է տալիս կրկնակի burst-եր (100՝ 12:00:59-ին և 100՝ 12:01:00-ին)։ Sliding window-ը հաշվի է առնում նախորդ պատուհանի քանակը՝ դա հարթելու համար։ Token bucket-ը յուրաքանչյուր client-ի տալիս է «դույլ», որը լցվում է կայուն արագությամբ մինչև առավելագույնը, ուստի կարճ burst-երը թույլատրվում են, իսկ երկարաժամկետ արագությունը մնում է ֆիքսված. սա համապատասխանում է իրական client-ների վարքագծին։ Counter-ները պահեք Redis-ում ատոմար գործողություններով, որպեսզի բոլոր app սերվերները կիսեն դրանք։ Key-երը ընտրեք զգույշ. ըստ API key-ի՝ գործընկերների համար, ըստ օգտատիրոջ՝ login արած տրաֆիկի համար, ըստ IP-ի՝ միայն որպես վերջին միջոց, քանի որ շատ օգտատերեր կարող են կիսել մեկ IP NAT-ի կամ մոբայլ օպերատորի հետևում։ Վերադարձրեք 429՝ Retry-After-ով, և թանկ կամ զգայուն endpoint-ների համար, ինչպես search-ը, login-ը և export-ները, օգտագործեք առանձին, ավելի խիստ limit-ներ։

1// Laravel: named limiters, applied with ->middleware('throttle:api')
2RateLimiter::for('api', function (Request $request) {
3    return $request->user()
4        ? Limit::perMinute(120)->by('user:'.$request->user()->id)
5        : Limit::perMinute(30)->by('ip:'.$request->ip());
6});
7 
8RateLimiter::for('login', fn (Request $request) =>
9    Limit::perMinute(5)->by($request->input('email').'|'.$request->ip())
10);

11Performance. payload-ի ձևը, N+1 և քեշավորում

Դանդաղ API-ների մեծ մասը դանդաղ է տվյալների բազայում։ List endpoint-ը, որը բեռնում է 50 պատվեր, հետո յուրաքանչյուրի համար query է անում հաճախորդին, կատարում է 51 query. սա N+1 խնդիրն է։ Eager-load արեք relation-ները, select արեք միայն անհրաժեշտ սյունակները և ավելացրեք index-ներ, որոնք համապատասխանում են ֆիլտրերին և դասավորությանը. development-ում log արեք query-ների քանակը յուրաքանչյուր հարցման համար։ Payload-ները ձևավորեք client-ի համար. sparse fieldset-ները (?fields=id,total,status) կամ include պարամետրերը (?include=customer) թույլ են տալիս մեկ endpoint-ին սպասարկել և՛ կոմպակտ ցուցակ, և՛ մանրամասն դիտում։ JSON-ը սեղմեք gzip-ով կամ Brotli-ով։ Շատ կարդացվող ռեսուրսների համար ուղարկեք ETag կամ Last-Modified, որպեսզի client-ները ստանան 304 պատասխաններ, և հաշվարկված պատասխանները քեշավորեք Redis-ում՝ գրառումների ժամանակ բացահայտ invalidation-ով։ Հրապարակային, ոչ անձնական endpoint-ները, ինչպես ապրանքների կատալոգը, կարելի է քեշավորել CDN-ում s-maxage-ով։ Չափեք p95 latency-ն ըստ endpoint-ի, ոչ թե միջինները։