HTTP هو Contract مش مجرد URL
REST API الجيدة تبدأ من resource model وعقد HTTP متوقع. العميل لا يحتاج معرفة إنك تستخدم EF Core أو SQL Server؛ يحتاج يعرف عنوان المورد، الأفعال المسموحة، شكل البيانات، الأخطاء، وكيف يتعامل مع التكرار والـ caching.
| Method | Intent | Safe? | Idempotent? |
|---|---|---|---|
| GET | Read representation | Yes | Yes |
| HEAD | GET metadata without body | Yes | Yes |
| POST | Create/action/process | No | Not by definition |
| PUT | Replace target state | No | Yes |
| PATCH | Partial modification | No | Depends on patch semantics |
| DELETE | Remove association/resource | No | Yes |
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.
| Operation | Retry intuition | Design note |
|---|---|---|
| GET /orders/7 | Usually safe to retry | Must not trigger hidden state change |
| PUT /profile/7 | Usually retryable | Send complete intended representation |
| DELETE /orders/7 | Idempotent effect | Response may differ on retry |
| POST /payments | Unsafe to blindly retry | Use 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
لو بدأت بالـ controller أولاً، غالباً ستصمم contract حسب ما هو سهل في C# لا حسب ما يحتاجه client. ابدأ بالـ capability وال resource lifecycle، ثم حدد method semantics، representation، errors، security، pagination/cache، versioning، ثم نفذ contract باستخدام ASP.NET Core. ده يخلي client و server يتفقوا على behavior قبل ما implementation تتغير.
Resource-oriented URLs و Statelessness
استخدم 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.
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.
Status Codes و Error Response Design
| Status | Meaning / Use |
|---|---|
| 200 OK | Success with representation |
| 201 Created | Resource created; often include Location |
| 202 Accepted | Accepted for asynchronous processing, not completed |
| 204 No Content | Success without response body |
| 400 Bad Request | Malformed or invalid request input |
| 401 Unauthorized | Missing/invalid authentication credentials |
| 403 Forbidden | Authenticated (or evaluated) but not permitted |
| 404 Not Found | Resource/route unavailable |
| 409 Conflict | Conflict with current resource state |
| 412 Precondition Failed | Conditional header evaluated false |
| 415 Unsupported Media Type | Unsupported request representation |
| 429 Too Many Requests | Rate limit exceeded |
| 500 Internal Server Error | Unexpected server failure |
| 503 Service Unavailable | Temporarily unable to serve |
RFC 9457 Problem Details يقدم format موحداً للأخطاء. لا تضع stack trace أو SQL message أو internal hostname في detail. يمكن إضافة extensions مثل error code و traceId؛ اجعل الـ client يعتمد على machine-readable code لا على نص الرسالة البشرية.
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: سيناريوهات متشابهة
| Situation | Typical status | Reason |
|---|---|---|
| Malformed JSON | 400 | Request cannot be parsed |
| No/invalid credentials | 401 | Authentication required/failed |
| Authenticated but not allowed | 403 | Authorization denied |
| Resource absent | 404 | Target not found |
| State conflict | 409 | Current resource state prevents operation |
| Failed If-Match | 412 | HTTP precondition failed |
| Accepted async work | 202 | Processing not complete |
| Rate limit exceeded | 429 | Client must slow down |
| Temporary dependency outage | 503 | Service 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 معاً.
Idempotency و Retries
Network failure قد يحدث بعد أن نفذ الخادم العملية وقبل أن يستلم العميل response. العميل لا يعرف هل العملية فشلت أم نجحت؛ لذلك retry ممكن يكرر الأثر. Idempotency key يعطي operation identity ثابتة عبر محاولات العميل. الخادم يخزن key ضمن scope المستخدم/العميل مع request fingerprint وحالة التنفيذ والنتيجة؛ نفس key ونفس payload يعيد نفس النتيجة، ونفس key مع payload مختلف يرفضه.
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 وتترك العميل بلا طريقة يعرف بها هل اكتملت العملية أو فشلت.
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.
HTTP Caching و ETag و Conditional Requests
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.
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 ثابتاً لبيانات متغيرة.
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 طويل.
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.
Pagination و PATCH Semantics
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 تعتمد على آخر مفتاح شوهد، وتطلب العناصر التي تأتي بعده في ترتيب ثابت.
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.
OpenAPI و Webhooks و HATEOAS
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.
Authentication Headers و Timeouts و Retry Policy
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 كما شرحنا.
Authorization: Bearer eyJ...
Accept: application/json
Content-Type: application/json
Idempotency-Key: 8c2a...
Retry-After: 30
Cache-Control: private, no-storeHTTP 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.
JSON Serialization و Content Negotiation عملياً
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.
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 تختلف في التفاصيل.
Knowledge Check
هل DELETE غير idempotent لأن أول طلب يرجع 204 والثاني قد يرجع 404؟
متى تستخدم 202 بدلاً من 200؟
ما الفرق بين ETag و Idempotency-Key؟
Offset أم Cursor لجدول ضخم يتغير باستمرار؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
خريطة التغطية: 25 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.