Api-blueprint: تحتاج إلى إجراءات متعددة من نفس فعل HTTP على نفس المورد (ولكن طلب مختلف من نوع المحتوى)

تحديث: أجد أنه يمكنني القيام بذلك من خلال ذكر إجابة واحدة فقط:

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

ومع ذلك ، لا يتم عرض هذا بشكل صحيح في الوضع المضمن (يعرض نوع طلب واحد فقط). تعد طرق عرض المعاينة والتوثيق داخل المحرر جيدة.

jrep

يبدو هذا باهتًا في تضمين Apiary الحالي (التصميم). لقد أخطرت فريق apiaryio بهذه المشكلة.

jrep هو الطلب هنا (بجانب القيد في التضمين) لدعم استجابات متعددة؟

إذا كان الأمر كذلك ، فيجب أن يكون ما يلي صالحًا بالفعل:

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

يوضح المثال الخاص بك طلبات متعددة ولكن استجابة واحدة فقط. هذا تمامًا مثل مثالي. نعم ، هذا صحيح نحويًا ، لكنه غير قادر على التعبير عما نحتاج إلى التعبير عنه.

نعم: هناك حاجة لإظهار "Response 200" مختلف لكل طلب. يتطابق نوع محتوى الاستجابة مع نوع محتوى الطلب (لذا فإن نوعين من محتوى الطلب يعني نوعين من محتوى الاستجابة) ، ولكن أيضًا المعلومات الواردة في الاستجابتين ليست مكافئة تمامًا.

باستخدام التنسيق القديم ، حددنا طلبًا واحدًا واستجابته ، ثم طلب / استجابة الزوج التالي. هذا خطأ نحوي في التنسيق الجديد ، ولا يبدو أن هناك أي طريقة صالحة لقول ذلك.

تحديث: عفوًا ، لم أبدو قريبًا بما فيه الكفاية: مثالك يختلف عن مثلك بطريقتين على الأقل: ردان ، واستخدام الطلبات المسماة. جرب ذلك الآن.

jrep

لست متأكدا كيف تقصد ذلك. هل يمكنك إرسال مقتطف من المخطط القديم من فضلك هنا؟

لن تسمح لي بطاقة Github بإرفاق نص. يمكنك الحصول على المخطط القديم من https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

فهمتك

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

أعتقد أنه من المقبول بشكل أساسي التعبير عن هذا على النحو التالي:

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

هذا مثال كلاسيكي على تفاوض المحتوى. قم بإنشاء مورد من العديد من التمثيلات المختلفة في حين أن الاستجابة ليس لها جسم وتذكر فقط موافق (وربما رابط إليها).

سيكون نظير تفاوض المحتوى لهذا هو:

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

أعتقد أن استجابة واحدة لطلبات متعددة تختلف في نوع المحتوى ولكن لها نفس المعنى (إنشاء مورد) هي التصميم الجيد. ومع ذلك ، أرغب في رفع هذا التقييد (التحذير عند وجود استجابات متعددة بنفس الحالة ونوع المحتوى) باستخدام https://github.com/apiaryio/snowcrash/issues/53

jrep تمت معالجة هذه المشكلة في https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) لذلك أقوم بإغلاقها. يرجى التعليق وإعادة الفتح إذا لزم الأمر.

على الرغم من أن نقطة النهاية يمكن أن تحتوي على أمثلة متعددة للمعاملات ، كما هو موضح في apiaryio / snowcrash # 53 ، لا يتم

خذ المثال التالي ...

لديك /oauth2/authorize ، والذي سيتعامل مع سيناريوهات مختلفة حسب المواصفات (مثل الحصول على رمز وصول من التحديث ، أو إنشاء رمز مميز من كلمة المرور ، إلخ). من الصعب جدًا على القارئ فهم دمج هذه العناصر في إجراء واحد على مستندات واجهة برمجة التطبيقات ، وبدلاً من ذلك يسهل على المستخدم الحصول على نقاط نهاية متعددة مثل "تحديث رمز الوصول" و "مصادقة المستخدم" في القائمة الجانبية. ومع ذلك ، هذا غير ممكن لأنه لا يمكنك تحديد نفس الطريقة / تركيبة عنوان URL مرتين.

هذا مثال رئيسي على المكان الذي تجبر فيه مواصفات واجهة برمجة التطبيقات مطوريها على استخدام نهج معين ، وفي حالات مثل المذكورة أعلاه ، لا يتناسب مع أنماط التصميم الشائعة.

أرى تمييزًا غير صحيح في البنية - راجع لون Body :