Api-blueprint: Perlu beberapa tindakan dari kata kerja HTTP yang sama pada sumber daya yang sama (tetapi tipe konten permintaan berbeda)

Pembaruan: Saya menemukan saya dapat melakukan ini dengan hanya menyatakan satu tanggapan:

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

Namun, ini tidak ditampilkan dengan benar dalam mode tersemat (hanya menampilkan satu jenis permintaan). Tampilan Pratinjau dan Dokumentasi dalam editor bagus.

@jrep

Ini tampaknya menjadi loyo dalam embed (desain) Apiary saat ini. Saya telah memberi tahu tim @apiaryio tentang masalah ini.

@jrep apakah permintaan di sini (di sebelah batasan dalam sematan) untuk mendukung banyak tanggapan?

Jika demikian, berikut ini seharusnya sudah valid:

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

Contoh Anda menunjukkan beberapa permintaan tetapi hanya satu tanggapan . Itu seperti contoh saya. Ya, itu valid secara sintaksis, tetapi tidak mampu mengungkapkan apa yang perlu kita ungkapkan.

Ya: kebutuhan di sini adalah menunjukkan "Respons 200" yang berbeda untuk setiap permintaan. Tipe konten respons cocok dengan tipe konten permintaan (jadi dua tipe konten permintaan berarti dua tipe konten respons), tetapi juga informasi dalam dua respons tidak persis sama.

Dengan format Legacy, kami mendefinisikan satu permintaan dan tanggapannya, lalu pasangan permintaan/tanggapan berikutnya. Itu kesalahan sintaks dalam format baru, dan sepertinya tidak ada cara yang valid untuk mengatakan ini.

Pembaruan: Ups, saya tidak melihat cukup dekat: contoh Anda berbeda dari saya setidaknya dalam dua cara: dua tanggapan, dan penggunaan permintaan bernama. Mencoba itu sekarang.

@jrep

Saya tidak yakin bagaimana maksud Anda. Bisakah Anda mengirimkan cuplikan cetak biru warisan di sini?

Tiket Github tidak mengizinkan saya melampirkan teks. Anda bisa mendapatkan cetak biru warisan dari https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

Mengerti

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

Saya pikir pada dasarnya OK untuk mengungkapkan ini sebagai:

## 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

Ini adalah Contoh Negosiasi Konten klasik. Buat sumber daya dari banyak representasi berbeda sementara respons tidak memiliki isi dan hanya menyatakan OK (dan mungkin tautan ke sana).

Mitra negosiasi konten untuk ini adalah:

### 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 ...

Saya pikir satu respons tanpa tubuh untuk beberapa permintaan yang berbeda dalam tipe konten tetapi memiliki arti yang sama (buat sumber daya) adalah desain yang bagus. Namun saya ingin mencabut batasan ini (peringatan ketika ada beberapa tanggapan dengan status dan tipe konten yang sama) dengan implementasi https://github.com/apiaryio/snowcrash/issues/53

@jrep Masalah ini telah diatasi di https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) oleh karena itu saya menutupnya. Silakan komentar & buka kembali jika diperlukan.

Meskipun titik akhir dapat memiliki beberapa contoh transaksi, seperti yang terlihat di apiaryio/snowcrash#53, ini tidak ditampilkan dengan sangat rapi di Apiary.

Ambil contoh berikut...

Anda memiliki /oauth2/authorize , yang menurut spesifikasi akan menangani berbagai skenario berbeda (seperti mendapatkan token akses dari penyegaran, atau membuat token dari kata sandi, dll). Menggabungkan ini menjadi satu tindakan pada dokumen API sangat sulit dipahami pembaca, sebaliknya lebih mudah bagi pengguna untuk memiliki beberapa titik akhir seperti "Segarkan token akses" dan "Otentikasi Pengguna" di menu samping. Namun ini tidak mungkin karena Anda tidak dapat menentukan kombinasi metode/URL yang sama dua kali.

Ini adalah contoh utama di mana Spesifikasi API memaksa pengembangnya untuk menggunakan pendekatan tertentu dan, dalam kasus seperti di atas, tidak cocok dengan pola desain umum.

Saya melihat sorotan sintaks yang salah - lihat warna Body :