Software Engineer Encyclopedia
0%
Domain 03 · Backend Engineering & Web Development · Topic 3.2

REST APIs وHTTP: تصميم عقد API احترافي

REST APIs & HTTP

تصميم resource-oriented APIs وفهم methods وstatus codes وheaders وidempotency وcaching وpagination وversioning وconditional requests.

  • Intermediate
  • ~21 min read
  • 10 sections
  • 10 code examples
  • 1 diagrams
  • 4 questions
  • Priority L1 · Essential
  • HTTP semantics · ASP.NET Core 10 · RFC 9110 / RFC 9457

المتطلبات قبل ما تبدأ

C# و.NET (المجال 02) والـ HTTP/Networking (درس 1.2).

مستوى التعمق المطلوب

DEEPDesign an API contract and explain its trade-offs.

01

HTTP هو Contract مش مجرد URL

Methods, status codes, headers, and bodies
Deep dive

REST API الجيدة تبدأ من resource model وعقد HTTP متوقع. العميل لا يحتاج معرفة إنك تستخدم EF Core أو SQL Server؛ يحتاج يعرف عنوان المورد، الأفعال المسموحة، شكل البيانات، الأخطاء، وكيف يتعامل مع التكرار والـ caching.

MethodIntentSafe?Idempotent?
GETRead representationYesYes
HEADGET metadata without bodyYesYes
POSTCreate/action/processNoNot by definition
PUTReplace target stateNoYes
PATCHPartial modificationNoDepends on patch semantics
DELETERemove association/resourceNoYes

Safe تعني أن semantics لا تطلب تغيير حالة الخادم. Idempotent تعني تكرار نفس الطلب عدة مرات له نفس الأثر المقصود مثل مرة واحدة، لا أن response bytes لازم تتطابق. PUT و DELETE idempotent من ناحية الأثر المقصود؛ POST ليس كذلك افتراضياً.

Headers تحمل metadata: Content-Type يصف body المرسل، Accept يعلن ما يقبله العميل، Authorization يحمل credentials، Cache-Control يحدد cache behavior، و ETag يحدد validator للـ representation. Route parameters تحدد هوية/جزء من المورد، query parameters تضبط filtering/paging/sorting، والـ body يحمل representation أو command input.

Safe و Idempotent: المعنى اللي يهم الـ Client

Safe method معناها أن العميل يطلب قراءة ولا يقصد تغيير state على الخادم. Idempotent معناها تكرار نفس الطلب مرة أو أكثر له نفس الأثر المقصود على server state. GET و HEAD و OPTIONS و TRACE safe حسب semantics؛ GET و PUT و DELETE و safe methods idempotent. POST ليس idempotent افتراضياً، و PATCH يعتمد على patch operation المصمم.

Idempotent لا تعني أن كل response bytes متطابقة: DELETE الأول قد يرجع 204 والثاني 404، لكن الأثر النهائي على المورد يظل محذوفاً. كذلك server قد يسجل metrics أو audit لكل محاولة؛ المقصود هو الأثر الأساسي على المورد. ده مهم جداً عند retries لأن الشبكة ممكن تفشل بعد تنفيذ العملية وقبل وصول response.

OperationRetry intuitionDesign note
GET /orders/7Usually safe to retryMust not trigger hidden state change
PUT /profile/7Usually retryableSend complete intended representation
DELETE /orders/7Idempotent effectResponse may differ on retry
POST /paymentsUnsafe to blindly retryUse idempotency key / operation resource

مراجعة عقد REST قبل كتابة Controller

ابدأ من resource nouns والـ lifecycle: ما الموارد؟ من يملكها؟ ما transitions المسموحة؟ ما representation التي يحتاجها client؟ بعد ذلك حدد HTTP methods/status codes، ثم validation/errors، pagination/filtering، auth، caching، idempotency، versioning. لا تبدأ بجدول SQL ثم تحاول تحويل كل column إلى endpoint.

مثال order: إنشاء order هو POST على collection، قراءة order هي GET على resource، إلغاء order قد يكون DELETE لو semantics تعني حذف المورد فعلاً، أو action subresource/command لو order يظل موجوداً بحالة Cancelled لأسباب audit. الـ URL يجب أن يعكس resource identity، لكن business action المعقدة لا يلزم إجبارها على CRUD وهمي.

حدد nullability والـ required fields والـ default behavior. وثّق هل empty collection ترجع 200 مع [] أو 404؛ غالباً collection موجودة حتى لو لا تحتوي records. لا تستخدم 404 لمجرد أن search result فاضية إلا لو contract يعرّفها ك resource محدد.

من Business Capability إلى HTTP Contract

BusinessResourcesHTTP SemanticsDTO ContractErrors + AuthPaging + CacheVersion + DocsThen choose framework and implementation
صمم contract قبل اختيار controller أو database implementation.

لو بدأت بالـ controller أولاً، غالباً ستصمم contract حسب ما هو سهل في C#‎ لا حسب ما يحتاجه client. ابدأ بالـ capability وال resource lifecycle، ثم حدد method semantics، representation، errors، security، pagination/cache، versioning، ثم نفذ contract باستخدام ASP.NET Core. ده يخلي client و server يتفقوا على behavior قبل ما implementation تتغير.

02

Resource-oriented URLs و Statelessness

Resource modeling and stateless interactions
Deep dive

استخدم nouns تمثل الموارد، وعبّر عن الفعل بالـ HTTP method: GET /orders/42، POST /orders، PUT /orders/42. لا تحول كل شيء إلى أفعال مثل /getOrder و /deleteOrder. بعض الأفعال التجارية لا تمثل CRUD طبيعياً؛ يمكن تمثيلها ك sub-resource أو command endpoint موثق بعناية، مثل POST /orders/42/cancellations.

Statelessness تعني أن كل request يحمل ما يلزم لمعالجته، ولا يعتمد الخادم على session memory مخفية بين الطلبات. هذا يسهل load balancing والـ horizontal scaling، لكنه لا يمنع وجود database أو distributed cache أو token state. Stateless لا تعني أن النظام بلا state إطلاقاً؛ تعني أن protocol interaction لا يتطلب server-side conversational state غير معلن.

Content negotiation عبر Accept/Content-Type يحدد representation. JSON هو الشائع، لكن يجب التعامل مع unsupported media types بـ415، و unacceptable response representation بـ406 عندما تطبق negotiation فعلاً. Serialization policy جزء من contract: أسماء الحقول، null handling، enum representation، date/time format، decimal precision، و compatibility.

Resource-Oriented URLs و PATCH

URL يعرّف resource أو collection؛ method يحدد العملية. GET /orders/42 قراءة order، و POST /orders إنشاء order، و DELETE /orders/42 حذف/إلغاء وفق contract. لا تحوّل كل فعل إلى endpoint verb مثل /getOrder أو /deleteOrder. لكن بعض business actions لها semantics واضحة مثل approve/cancel؛ يمكن تمثيلها sub-resource أو action endpoint عندما لا يكون CRUD كافياً.

PATCH يعني partial modification، لكن لازم تحدد format. JSON Patch يستخدم operations مثل add/replace/remove على JSON Pointer paths، بينما JSON Merge Patch يعبر عن partial object ويستخدم null لمعنى حذف member. لا تفترض أن كل PATCH هو “ابعت أي fields ناقصة” من غير contract. حدد هل الحقول الغائبة تعني no change، وهل null مسموح كقيمة أم delete.

HTTPExample JSON Merge Patch
PATCH /api/products/42 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v7"

{
  "description": "Updated description",
  "discountPrice": null
}

في المثال، semantics الخاصة بـ null تعتمد على Merge Patch contract؛ لا تنفذ update عشوائي على entity بمجرد deserialize partial DTO. الأفضل تمثيل presence/absence بوضوح، ثم تطبيق قواعد domain و concurrency.

Statelessness و Content Negotiation

Statelessness في REST تعني أن كل request يحمل context كافياً لمعالجته، ولا يعتمد server على conversation state مخفية في memory بين requests. ده لا يمنع وجود database أو session store؛ المقصود أن server لا يحتاج يتذكر request السابقة لنفس client لكي يفهم الحالية. statelessness تساعد load balancing و horizontal scaling، لكن authentication tokens/cookies ما زالت تحمل أو تشير إلى identity/session.

Content negotiation تسمح للعميل يعلن representation المقبولة عبر Accept، والـ server يحدد representation ويكتب Content-Type. في JSON-only APIs أبقِ السلوك بسيطاً ومتوقعاً. لو تدعم version/media type في Accept، وثّق precedence و error behavior. لا تستخدم 406 Not Acceptable بشكل مفاجئ لو API contract لم يوضح supported formats.

03

Status Codes و Error Response Design

Make outcomes predictable
Deep dive
StatusMeaning / Use
200 OKSuccess with representation
201 CreatedResource created; often include Location
202 AcceptedAccepted for asynchronous processing, not completed
204 No ContentSuccess without response body
400 Bad RequestMalformed or invalid request input
401 UnauthorizedMissing/invalid authentication credentials
403 ForbiddenAuthenticated (or evaluated) but not permitted
404 Not FoundResource/route unavailable
409 ConflictConflict with current resource state
412 Precondition FailedConditional header evaluated false
415 Unsupported Media TypeUnsupported request representation
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorUnexpected server failure
503 Service UnavailableTemporarily unable to serve

RFC 9457 Problem Details يقدم format موحداً للأخطاء. لا تضع stack trace أو SQL message أو internal hostname في detail. يمكن إضافة extensions مثل error code و traceId؛ اجعل الـ client يعتمد على machine-readable code لا على نص الرسالة البشرية.

HTTPExample Problem Details response
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/stock-conflict",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "The requested quantity is no longer available.",
  "instance": "/api/orders/42",
  "code": "inventory.insufficient_stock",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

اختيار Status Code: سيناريوهات متشابهة

SituationTypical statusReason
Malformed JSON400Request cannot be parsed
No/invalid credentials401Authentication required/failed
Authenticated but not allowed403Authorization denied
Resource absent404Target not found
State conflict409Current resource state prevents operation
Failed If-Match412HTTP precondition failed
Accepted async work202Processing not complete
Rate limit exceeded429Client must slow down
Temporary dependency outage503Service temporarily unavailable

401 غالباً يحتاج WWW-Authenticate challenge. 403 لا يعني «token غلط»؛ يعني identity معروفة لكن access مرفوض. 404 أحياناً يستخدم لإخفاء وجود resource عن unauthorized user، لكن ده security policy قرار وليس قاعدة عامة. اختر consistent semantics واكتبها في OpenAPI.

Error Contract و Problem Details

Client يحتاج يعرف هل يعيد المحاولة، يطلب login، يغير input، أو يعرض conflict. لذلك errors ليست مجرد text. Problem Details مع stable error code و field errors يساعد client. 429 قد يحمل Retry-After؛ 503 قد يحمل Retry-After؛ 401 يحتاج challenge؛ 412 يعني client لازم يقرأ أحدث representation ثم يعيد التعديل إذا مناسب.

لا ترجع 200 لكل شيء وتحط success=false داخل JSON؛ ده يكسر HTTP semantics والـ proxies/SDKs/monitoring. كذلك لا ترجع 500 لكل expected business condition. اختار status code و error code معاً.

04

Idempotency و Retries

Design for duplicate delivery
Deep dive

Network failure قد يحدث بعد أن نفذ الخادم العملية وقبل أن يستلم العميل response. العميل لا يعرف هل العملية فشلت أم نجحت؛ لذلك retry ممكن يكرر الأثر. Idempotency key يعطي operation identity ثابتة عبر محاولات العميل. الخادم يخزن key ضمن scope المستخدم/العميل مع request fingerprint وحالة التنفيذ والنتيجة؛ نفس key ونفس payload يعيد نفس النتيجة، ونفس key مع payload مختلف يرفضه.

TextIdempotency contract (conceptual)
POST /payments
Authorization: Bearer <access-token>
Idempotency-Key: 4f9b...unique-client-generated-key
Content-Type: application/json

{ "orderId": 42, "amount": 125.00, "currency": "EGP" }

المفتاح ليس سحراً: يجب تخزينه بشكل ذري مع business operation أو عبر transaction/outbox strategy؛ وإلا قد يحدث race بين طلبين بنفس key. احتفظ به لمدة معلنة، واستخدم TTL، وخزّن fingerprint لمنع إعادة استعمال المفتاح لمحتوى آخر. Rate limiting يحدد معدل الاستخدام؛ لا يساوي quota تجارية ولا يحل abuse من كل المصادر وحده.

Long-running operation غالباً يرجع 202 Accepted مع Location إلى status resource مثل /operations/{id}، والعميل يعمل polling أو يتلقى webhook/SSE عند الاكتمال. 202 لا تعني أن المعالجة نجحت؛ تعني أنها قُبلت للمعالجة.

Timeouts و Retries و Long-Running Operations

Timeout يحدد أقصى وقت تنتظره العملية، لكنه لا يضمن أن الخادم أوقف التنفيذ فعلاً؛ لازم cancellation ينتقل عبر طبقات التطبيق. Retry يزيد فرص النجاح مع transient failures لكنه يضاعف load أثناء outage إذا كان بلا limits. استخدم exponential backoff مع jitter، maximum attempts، overall deadline، و retry budget. لا تعمل retry على كل status code أو كل exception.

لعملية تستغرق وقتاً طويلاً، 202 Accepted يعني أن server قبل الطلب لكنه لم ينهه. ارجع operation ID أو Location إلى status resource مثل /operations/{id}. لا ترجع 202 وتترك العميل بلا طريقة يعرف بها هل اكتملت العملية أو فشلت.

HTTPAccepted operation contract
POST /api/reports HTTP/1.1

HTTP/1.1 202 Accepted
Location: /api/operations/op_81f3
Retry-After: 3
Content-Type: application/json

{ "operationId": "op_81f3", "status": "queued" }

في عمليات مالية أو create commands، retry الآمن يحتاج idempotency design. الـ retry policy في HttpClient لا تعرف business meaning من نفسها. اجعل client يرسل idempotency key، واجعل server يخزن النتيجة ويمنع تنفيذ الأثر مرتين.

Client Behavior: Retry و Timeout و Cancellation

API contract لا يكتمل من غير توضيح client behavior. Client يحدد timeout مناسب، يمرر cancellation عند navigation/close، يعيد المحاولة فقط للأخطاء transient، ويحترم Retry-After عند 429/503. Server يحدد deadline budget، ويرجع status واضحاً، ويمنع duplicate side effects باستخدام idempotency. الطرفان مسؤولان عن resilience؛ retry في client بلا server idempotency قد يكرر الدفع أو إنشاء الطلب.

لا تجعل timeout الخاص بكل hop أكبر من overall user request deadline. لو mobile client عنده 10 ثوانٍ، لا تسمح لخمس dependencies أن تنتظر كل واحدة 10 ثوانٍ بالتتابع. وزّع budget، وألغِ العمل downstream عند انتهاء request. سجل timeout category لتعرف هل التأخير في API أو dependency.

05

HTTP Caching و ETag و Conditional Requests

Validators and optimistic concurrency
Deep dive

HTTP caching يمكن أن يكون browser cache أو proxy/CDN. Cache-Control: public, max-age=60 يسمح بتخزين response المشتركة لمدة دقيقة؛ private يحد التخزين للـ private cache؛ no-store يمنع التخزين. لا تستخدم public caching لبيانات حسب المستخدم.

ETag validator يمثل نسخة representation. العميل يرسل If-None-Match في GET؛ لو لم تتغير النسخة يرجع الخادم 304 Not Modified بلا body. في update يرسل If-Match؛ لو النسخة الحالية لا تطابق يرجع 412 Precondition Failed. هذا يقلل نقل البيانات ويحمي من lost updates.

HTTPConditional read / write
GET /api/products/42
If-None-Match: "product-42-v7"

HTTP/1.1 304 Not Modified
ETag: "product-42-v7"

PUT /api/products/42
If-Match: "product-42-v7"
Content-Type: application/json

{ "name": "Keyboard Pro", "price": 1400 }

HTTP Caching: Cache-Control و ETag

HTTP caching مش مجرد وضع response في Redis. Browser/proxy caches تفهم headers قياسية. Cache-Control: max-age يحدد freshness lifetime؛ private يمنع shared caches من تخزين response؛ no-store يطلب عدم التخزين؛ no-cache يسمح بالتخزين لكن يطلب revalidation قبل إعادة الاستخدام. لا تخلط بين no-cache و no-store.

ETag validator يتيح conditional GET باستخدام If-None-Match. لو representation لم تتغير، server يرجع 304 من غير body، والعميل يستخدم cached copy. للـ update، If-Match يحقق optimistic concurrency. لازم تتعامل مع weak/strong validators وفق نوع المقارنة، ولا تضع ETag ثابتاً لبيانات متغيرة.

HTTPConditional GET exchange
GET /api/catalog HTTP/1.1
If-None-Match: "catalog-v12"

HTTP/1.1 304 Not Modified
ETag: "catalog-v12"
Cache-Control: public, max-age=60

الـ caching policy يجب أن تراعي Authorization و cookies و tenant. لا تسمح shared cache بتخزين response شخصية ثم تقديمها لمستخدم آخر. استخدم Vary عند اختلاف representation بناءً على request headers، لكن لا تستخدم Vary عشوائياً مع headers كثيرة تسبب cache fragmentation.

Conditional Requests: If-None-Match و If-Match

Conditional requests تربط HTTP validators بالـ resource version. GET مع If-None-Match يسمح للعميل يقول «لو representation لم تتغير، لا تبعت body». Server يرد 304 Not Modified. PUT/PATCH مع If-Match يقول «نفذ التعديل فقط لو النسخة ما زالت هي التي قرأتها». لو validator لا يطابق، يرجع 412. ده يمنع lost updates بدون lock طويل.

HTTPOptimistic update exchange
GET /api/products/42

HTTP/1.1 200 OK
ETag: "product-42-v8"

PATCH /api/products/42
If-Match: "product-42-v8"
Content-Type: application/merge-patch+json

{ "price": 125.00 }

HTTP/1.1 204 No Content
ETag: "product-42-v9"

الـ ETag يجب أن يتغير عند أي تغيير يؤثر على representation التي يحميها. لو ETag يحمي جزءاً من البيانات فقط، وضح ذلك. لا تقارن ETag string بيدك من غير مراعاة weak/strong comparison semantics.

06

Pagination و PATCH Semantics

Offset, cursor, JSON Patch, Merge Patch
Practical

Offset مثال: ?page=3&pageSize=20. مناسب للجداول الصغيرة والواجهات التي تحتاج jump-to-page، لكن offset الكبير قد يؤدي إلى scan/skip مكلف وعدم استقرار النتائج مع تغيّر البيانات. Cursor pagination مثال: ?after=eyJpZCI6...، أكثر استقراراً في feeds كبيرة مع ordering ثابت ومفتاح فريد، لكنه لا يدعم الانتقال العشوائي لصفحة 50 بنفس السهولة.

Filtering/sorting لازم تكون allow-listed: لا تبني SQL column names من query string مباشرة. حد أقصى للـ page size، تحقق من sort key/direction، ووضح semantics للـ nulls/collation/timezone. PATCH ليس نوعاً واحداً من التعديل؛ JSON Patch (RFC 6902) يستخدم operations مثل add/remove/replace، و JSON Merge Patch (RFC 7396) يستخدم partial JSON document مع semantics خاصة لـ null. اختَر وعرّف contract بدقة، وطبّق authorization/validation على كل حقل قابل للتغيير.

Offset vs Cursor Pagination

Offset pagination سهلة: ?page=3&pageSize=20 تتحول إلى skip/take. لكنها قد تكون مكلفة مع offset عميق لأن DB قد تقرأ وتتخطى صفوف كثيرة. كما أن insert/delete أثناء تصفح الصفحات قد يجعل عنصر يتكرر أو يتخطى. Cursor/keyset pagination تعتمد على آخر مفتاح شوهد، وتطلب العناصر التي تأتي بعده في ترتيب ثابت.

C#Keyset pagination with a unique tie-breaker
var query = db.Orders.AsNoTracking()
    .Where(o => o.CustomerId == customerId);

if (cursor is not null)
{
    query = query.Where(o =>
        o.CreatedAt < cursor.CreatedAt ||
        (o.CreatedAt == cursor.CreatedAt && o.Id < cursor.Id));
}

var rows = await query
    .OrderByDescending(o => o.CreatedAt)
    .ThenByDescending(o => o.Id)
    .Take(pageSize + 1)
    .Select(o => new OrderRow(o.Id, o.CreatedAt, o.Total))
    .ToListAsync(token);

لازم sort يكون deterministic ويحتوي unique tiebreaker. Cursor ممكن يكون opaque وموقع HMAC لو يحمل state لا تريد العميل يعدله. لا تضع SQL أو internal column names في cursor. حدد page size بحد أقصى، وتحقق من filters/sort keys من allow-list.

07

OpenAPI و Webhooks و HATEOAS

Contract tooling and event delivery choices
Practical

OpenAPI document يصف endpoints، parameters، request/response schemas، auth schemes، status codes، descriptions و examples. يُستخدم لتوليد docs/SDKs والتحقق من contract؛ لكنه لا يضمن أن implementation مطابق للوثيقة من غير tests أو contract checks.

اختيار async notification: polling أبسط لكنه يكرر الطلبات ويضيف latency؛ SSE يدعم server-to-client stream عبر HTTP؛ webhook يجعل الخادم يرسل POST إلى endpoint لدى consumer. Webhooks تحتاج signature HMAC على raw body، timestamp/replay protection، retries مع backoff، delivery ID، idempotent consumer، و dead-letter/observability. HATEOAS يضيف links/actions في representations لتوجيه العميل عبر hypermedia؛ مهم معرفياً، لكن كثيراً من APIs العملية تستخدم contracts ثابتة و OpenAPI بدون تطبيق REST hypermedia الكامل.

قرار تصميم عملي

اكتب contract قبل implementation: resource paths، verbs، status codes، error schema، auth، pagination، versioning، retry/idempotency، caching. كل نقطة مبهمة ستتحول لاحقاً إلى اختلاف بين client و server.

Versioning و HATEOAS و Webhooks و SSE

HATEOAS يضيف links داخل representation لتوجيه العميل إلى transitions المتاحة. الفكرة أن client يتبع links بدل أن hardcode كل URI. في كثير من APIs الحديثة يتم استخدام links بشكل محدود وليس REST maturity requirement لكل مشروع. اعرف المفهوم وتكلفته؛ لا تبنِ link graph معقداً لو client contract بسيط وواضح.

Webhook مقابل polling مقابل SSE: polling client يسأل server كل فترة؛ webhook server يرسل event إلى endpoint عند client؛ SSE يفتح stream server-to-client. webhook مناسب system-to-system event notification لكنه يحتاج signature/retry/idempotency. SSE مناسب progress/feed أحادي الاتجاه. SignalR يقدم abstraction أوسع للـ real-time communication.

Versioning لا يعني أن كل version لها database schema منفصل. قد تشترك versions في application/domain model وتستخدم adapters/DTOs مختلفة. لا تكشف internal versioning strategy للعميل إلا بقدر ما يحتاجه العقد. استخدم deprecation headers أو docs policy عندما توقف endpoint.

Long-running Commands و Webhooks

لو export report يحتاج 40 ثانية، لا تترك mobile request مفتوحاً بلا timeout. POST command يرجع 202 و operation resource؛ GET operation status يرجع queued/running/succeeded/failed، ويمكن توفير result URL بعد اكتماله. حدد expiry للـ operation record، authorization على status/result، و retry semantics عند client reconnect.

Webhook delivery asynchronous وممكن تتكرر أو تفشل. event ID ثابت، signature verification، timestamp، retry with backoff، delivery history، و idempotent consumer أساسيات. SSE مناسب للـ browser لمتابعة operation progress لو تحتاج server push أحادي الاتجاه، بينما polling أبسط لو التحديث قليل.

Contract Versioning عملياً

Breaking changes تشمل حذف path/field، تغيير field type، جعل input اختياري required، تغيير status semantics، أو إضافة auth requirement إلى endpoint كان public. Additive fields غالباً آمنة لكن generated clients و strict deserializers قد تتأثر. enum additions قد تكسر switch exhaustive. لذلك versioning policy تشمل schema diff و consumer testing و deprecation telemetry.

لا تخلط API version مع application release version. ممكن تنشر backend release كثيرة مع بقاء v1 contract ثابتاً. ولا تنشئ v2 لمجرد تغيير implementation داخلي. احتفظ بـ adapters/DTOs منفصلة عند الحاجة حتى domain model لا يصبح نسخة من كل public API.

08

Authentication Headers و Timeouts و Retry Policy

Credentials and transient network failures
Deep dive

Bearer token يُرسل في Authorization: Bearer ... وليس query string؛ URLs قد تظهر في history, proxy logs, analytics, referrer headers. TLS يحمي token أثناء النقل، لكن لا يحميه من logging أو XSS أو سرقة الجهاز. لا تستخدم Basic Authentication إلا فوق TLS ومع إدارة credentials مناسبة. API key غالباً يعرّف client/application وليس user identity، فلا تخلط بينه وبين access token ذي claims.

Timeouts يجب أن تكون bounded على كل dependency؛ request timeout العام لا يكفي لو downstream HTTP/DB له وقت انتظار لا نهائي. ميزانية الوقت end-to-end: لو العميل يسمح 5s، لا تجعل كل service تنتظر 5s كاملة وراء الأخرى. Propagate cancellation، واضبط client/server deadlines.

Retry مفيد لأخطاء transient مثل بعض 502/503/connection resets، مع exponential backoff و jitter وحد أقصى. لا تعيد 400/401/403 غالباً؛ لا تعمل retries متزامنة من كل clients لأنها قد تضاعف الضغط بعد outage (retry storm). راعِ Retry-After في 429/503 عندما يقدمه الخادم. Retry non-idempotent request يحتاج idempotency key/deduplication كما شرحنا.

HTTPCommon auth and retry-related headers
Authorization: Bearer eyJ...
Accept: application/json
Content-Type: application/json
Idempotency-Key: 8c2a...
Retry-After: 30
Cache-Control: private, no-store

HTTP Headers اللي لازم تفهمها

Headers تحمل metadata ولا تستبدل body. أمثلة مهمة: Authorization للـ credentials، Accept للـ representation المقبولة، Content-Type لنوع body، Cache-Control للتخزين، ETag للـ validator، Location لمكان resource/operation، Retry-After لتوقيت retry، Vary لاختلاف representation حسب request headers، و WWW-Authenticate لتحدي authentication.

لا تضع credentials أو بيانات حساسة في URL لأن URLs قد تظهر في browser history و proxy logs و analytics. لا تستخدم custom header كأنه security mechanism من غير server enforcement. Headers لها size limits في servers/proxies؛ لا تحمل JSON كبيراً في header.

Headers: Authorization و Location و Retry-After و Vary

Headers لها semantics متفق عليها؛ استخدم القياسي قبل custom header. Authorization يحمل credentials، WWW-Authenticate يوضح challenge، Location يحدد resource created أو operation status، Retry-After يقترح متى يعيد client المحاولة، Vary يحدد headers التي أثرت في representation، Cache-Control يحدد freshness/storage. Custom headers ممكنة لكن لا تستبدل semantics قياسية.

لا تضع access token في URL query. لا تجعل custom header مثل X-User-Id يحدد هوية المستخدم؛ server يستخرج identity من credentials الموثوقة. Forwarded headers تحتاج trusted proxy configuration حتى لا يستطيع client تزوير scheme/client IP.

09

JSON Serialization و Content Negotiation عملياً

Schema stability and representation choices
Practical

JSON serialization ليست تفصيلة داخلية فقط: casing policy، enum-as-string أو number، DateTimeOffset، decimal precision، null omission، polymorphism، maximum depth، circular references كلها قد تغير client behavior. استخدم UTC instants بـ DateTimeOffset، ووضح currency/units، ولا تحوّل money إلى floating-point binary approximation في contracts المالية. لا تسمح لـ arbitrary polymorphic type metadata من input غير موثوق.

Content negotiation يتعامل مع Accept header؛ إذا API تنتج JSON فقط فكن واضحاً، ولا تعد بـ XML/CSV من غير formatter/configuration. Version schema بطريقة backward compatible قدر الإمكان: add optional field بدلاً من rename/remove، وراقب clients الذين يعتمدون على unknown field behavior.

Content Negotiation و JSON Serialization

Resource واحد ممكن يكون له أكثر من representation، لكن معظم JSON APIs تستخدم application/json. Header Accept يوضح media types التي يقبلها client، و Content-Type يوضح نوع body المرسل أو الراجع. لا تخلط بينهم. لو endpoint يستقبل JSON فقط، وثّق media type وارفض unsupported media type بطريقة واضحة.

JSON serialization يحدد property naming، enum representation، date/time format، null handling، number precision، و reference handling. تغيير global serializer options ممكن يكسر client قديم حتى لو C#‎ DTO لم يتغير. استخدم UTC/offset-aware timestamps، ولا ترسل money كـ floating-point double لو precision المالية مهمة؛ decimal JSON number أو minor-unit integer حسب contract.

C#Explicit JSON options
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.SerializerOptions.DefaultIgnoreCondition =
        JsonIgnoreCondition.WhenWritingNull;
    options.SerializerOptions.Converters.Add(
        new JsonStringEnumConverter(JsonNamingPolicy.CamelCase));
});

قبل تغيير enum من numeric إلى string representation، افحص client compatibility. لا تعرض internal CLR type names كجزء من API contract. وللـ content negotiation الكامل، اختبر Accept headers و response Content-Type على actual endpoints؛ بعض Minimal API/controller defaults تختلف في التفاصيل.

10

Knowledge Check

HTTP reasoning questions
Basics
هل DELETE غير idempotent لأن أول طلب يرجع 204 والثاني قد يرجع 404؟
لا يلزم. Idempotency تتعلق بالأثر المقصود على الحالة؛ حذف مورد موجود مرتين لا يغير النتيجة النهائية بعد المرة الأولى. قد تختلف status responses عبر المحاولات.
متى تستخدم 202 بدلاً من 200؟
عندما قبلت العملية لكن لم تكتمل بعد، وتوفّر contract لمتابعة الحالة/النتيجة.
ما الفرق بين ETag و Idempotency-Key؟
ETag validator لنسخة representation يستخدم للتخزين المشروط أو optimistic concurrency؛ Idempotency-Key يعرّف عملية منطقية واحدة لمنع تكرار أثر retries.
Offset أم Cursor لجدول ضخم يتغير باستمرار؟
غالباً cursor/keyset مع ترتيب ثابت ومفتاح فريد؛ لأنه يتجنب offsets العميقة ويقلل تحرك الصفوف بين الصفحات.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 25 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapHTTP Methods and Status Codes§01
RoadmapHTTP Headers§01
RoadmapRequest Body vs Query Parameters vs Route Parameters§01
RoadmapSafe and Idempotent Methods§02
RoadmapResource-Oriented URLs§02
RoadmapStatelessness§02
RoadmapContent Negotiation§02
RoadmapJSON Serialization§01
RoadmapPagination§06
RoadmapFiltering and Sorting§06
RoadmapAPI Versioning§06
RoadmapError Response Design§03
RoadmapAuthentication Headers§01
RoadmapCaching Headers§05
RoadmapTimeouts and Retries§04
RoadmapIdempotency Keys§04
RoadmapRate Limiting§04
RoadmapOpenAPI Contracts§07
SuggestedRFC 9457 Problem Details§03
SuggestedConditional requests (ETag, If-Match, If-None-Match)§05
SuggestedLong-running operations (202 Accepted + status endpoint)§04
SuggestedCursor vs offset pagination§06
SuggestedPATCH semantics (JSON Patch vs Merge Patch)§06
SuggestedWebhooks vs polling vs SSE§07
SuggestedHATEOAS (know it, rarely needed)§07

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس