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

यह वर्तमान एपीरी एंबेड (डिज़ाइन) में एक कमी प्रतीत होती है। मैंने @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

आपका उदाहरण एकाधिक अनुरोध दिखाता है लेकिन केवल एक प्रतिक्रिया दिखाता है। यह बिल्कुल मेरे उदाहरण जैसा है। हां, यह वाक्यात्मक रूप से मान्य है, लेकिन यह व्यक्त करने में सक्षम नहीं है कि हमें क्या व्यक्त करने की आवश्यकता है।

हां: यहां प्रत्येक अनुरोध के लिए एक अलग "प्रतिक्रिया 200" दिखाने की आवश्यकता है। प्रतिक्रिया सामग्री-प्रकार अनुरोध सामग्री-प्रकार से मेल खाता है (इसलिए दो अनुरोध सामग्री-प्रकार का अर्थ है दो प्रतिक्रिया सामग्री-प्रकार), लेकिन दो प्रतिक्रियाओं में जानकारी भी बिल्कुल समान नहीं है।

लीगेसी प्रारूप के साथ, हमने एक अनुरोध और उसकी प्रतिक्रिया को परिभाषित किया, फिर अगला अनुरोध/प्रतिक्रिया जोड़ी। यह नए प्रारूप में एक सिंटैक्स त्रुटि है, और ऐसा कहने का कोई मान्य तरीका प्रतीत नहीं होता है।

अपडेट करें: ओह, मैंने काफी करीब नहीं देखा: आपका उदाहरण कम से कम दो तरीकों से मेरे से अलग है: दो प्रतिक्रियाएं, और नामित अनुरोधों का उपयोग। अब यह कोशिश कर रहे हैं।

@jrep

मुझे यकीन नहीं है कि आपका क्या मतलब है। क्या आप कृपया यहां विरासती खाका का एक अंश प्रस्तुत कर सकते हैं?

जीथब टिकट मुझे टेक्स्ट संलग्न नहीं करने देगा। आप 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 (स्नो क्रैश v0.10.0) में संबोधित किया गया था इसलिए मैं इसे बंद कर रहा हूं। कृपया टिप्पणी करें और यदि आवश्यक हो तो फिर से खोलें।

हालांकि एक समापन बिंदु में कई लेन-देन के उदाहरण हो सकते हैं, जैसा कि apiaryio/snowcrash#53 में देखा गया है, ये Apiary में बहुत सफाई से प्रस्तुत नहीं करते हैं।

निम्नलिखित उदाहरण लें ...

आपके पास /oauth2/authorize , जो विनिर्देश द्वारा विभिन्न विभिन्न परिदृश्यों को संभालेगा (जैसे रीफ्रेश से एक्सेस टोकन प्राप्त करना, या पासवर्ड से टोकन उत्पन्न करना आदि)। एपीआई डॉक्स पर एक ही क्रिया में इनका विलय होना पाठक के लिए समझना बहुत कठिन है, इसके बजाय उपयोगकर्ता के लिए साइड मेन्यू में "रीफ्रेश एक्सेस टोकन" और "ऑथेंटिक यूजर" जैसे कई एंडपॉइंट होना आसान है। हालांकि यह संभव नहीं है क्योंकि आप एक ही विधि/यूआरएल संयोजन को दो बार निर्दिष्ट नहीं कर सकते हैं।

यह एक प्रमुख उदाहरण है जहां एपीआई विशिष्टता अपने डेवलपर्स को एक निश्चित दृष्टिकोण का उपयोग करने के लिए मजबूर कर रही है और उपरोक्त मामलों में, सामान्य डिजाइन पैटर्न के साथ फिट नहीं है।

मुझे गलत सिंटैक्स हाइलाइट दिखाई देता है - Body का रंग देखें: