Mendokumentasikan antarmuka REST dengan diagram alur

9

Adakah yang punya saran untuk membuat diagram alur dari antarmuka web gaya REST? Untuk kepentingan menyediakan dokumentasi menyeluruh kepada pengembang bersama, saya telah mempermainkan antarmuka model untuk memodifikasi dan menghasilkan sumber daya produk:

masukkan deskripsi gambar di sini

Sistem khusus ini mulai bertindak secara berbeda dengan otentikasi pengguna / sumber daya, jadi sebelum saya melakukan modifikasi, saya mencari beberapa klarifikasi:

  • Kompleksitas: bagaimana Anda menyederhanakan struktur keseluruhan untuk membuatnya lebih mudah dibaca?
  • Simbol Tampilan: apakah ini pantas untuk mewakili halaman?
  • Simbol Operasi Manual: apakah ini sesuai untuk mewakili tindakan pengguna seperti klik tombol?

Saran lain akan sangat dihargai.

Permintaan maaf saya untuk posting ulang. Situs stackexchange utama menyarankan pertanyaan ini lebih baik disajikan pada programmer.

documentation rest flowchart James Kassemi
sumber

Jawaban:

12

Saya merasa Message Sequence Chart / Sequence diagram lebih cocok untuk mendokumentasikan interaksi API RESTful. Apa yang Anda miliki adalah diagram keadaan, sedangkan RESTful API menurut definisi adalah stateless.

masukkan deskripsi gambar di sini

vartec
sumber
5
Server dalam arsitektur RESTful tidak memiliki kewarganegaraan, namun sistemnya sendiri tidak. Status disimpan di klien, dan transisi status yang mungkin dikodekan dalam representasi sumber daya sehingga klien dapat memulai transisi ke keadaan baru dengan membuat permintaan ke server. Saya pikir diagram keadaan cukup efektif untuk mengkomunikasikan keadaan sistem secara keseluruhan, bahkan jika tidak secara tepat mendokumentasikan permintaan dan tanggapan antara komponen klien dan server.
Adam Jaskiewicz
1
@ Adam: Anda benar tentang sistem secara keseluruhan. Tapi pertanyaannya secara eksplisit bertanya tentang mendokumentasikan antarmuka REST, bukan seluruh sistem.
vartec
Terima kasih, vartec, MSC secara efektif mendokumentasikan antarmuka REST dalam hal ini. Saya masih penasaran untuk mendengar peningkatan pada dokumentasi model ini tentang keadaan klien.
James Kassemi
1
SISA sistem yang menerapkan batasan hypertext menyebabkan klien untuk bertindak sebagai mesin negara. Saya telah menemukan menggunakan diagram tipe mesin negara untuk menjadi alat yang jauh lebih efektif untuk mendokumentasikan interaksi klien / server yang tenang.
Darrel Miller
Apakah mungkin untuk menggambarkan if-s dan while-s dalam diagram ini?
hellboy
1

Saya pasti berpikir mesin negara adalah cara yang tepat untuk mendokumentasikan interaksi sistem RESTful. Namun, saya masih bekerja pada cara yang tepat untuk mewakili faktor hypermedia dalam diagram. Berikut adalah beberapa diagram eksperimental yang telah saya lakukan.

Labirin

masukkan deskripsi gambar di sini

Darrel Miller
sumber
0

Dua uang saya pada subjek, karena saya sedang mengerjakan ini saat ini:

  • fokus pada sumber daya dan hubungan mereka
    • dan bukan pada tindakan, dan dengan demikian metode HTTP
    • ketika Anda mengikuti tautan, tidak peduli apakah Anda melakukan GET atau POST, status Anda selanjutnya mungkin ditentukan terutama oleh sumber daya saat ini, dan apalagi dengan metode HTTP permintaan

Dengan mengingat hal itu:

  • menghapus beberapa tautan yang jelas (mis. ke diri sendiri, untuk me-root)
  • hapus label relasi jika hanya menyatakan "[mobil] ini memiliki [pemilik]", di mana sumber daya adalah mobil dan sumber daya target adalah pemilik. Itu tidak menambahkan apa pun
  • grafik interaktif dapat sangat membantu dengan diagram keadaan kompleks ( contoh )
Andrei Neculau
sumber