Representasi referensi yang tenang - tautan semantik vs uri

9

Kami sedang merancang API TENANG untuk membuka informasi akun pelanggan kami. Kami memiliki representasi yang berisi referensi ke sumber daya lain yang terkait dengan sumber daya saat ini. Ini dari sejumlah praktik terbaik yang dapat kami temukan di API publik serta materi yang dipublikasikan. Representasi dapat berupa XML atau JSON.

Misalnya untuk sumber daya akun kami akan memiliki referensi ke alamat akun dan untuk sumber daya daftar paginasi, kami akan memiliki referensi ke halaman pertama, berikutnya, dan sebelumnya.

API pertama kali dirancang menggunakan tautan semantik <link title="" rel="" href="" />seperti yang dijelaskan dalam buku O'Reilly dan digunakan dalam API oleh Netflix dan Google. Ketika tiba saatnya bagi teknisi QA kami untuk menulis rangkaian otomatisasi, mereka mengalami masalah deserialisasi tautan. Kami sekarang menyarankan elemen string uri yang lebih sederhana yang telah digunakan di API oleh Facebook dan Twitter.

Insinyur QA kami telah memecahkan masalah deserialisasi mereka, tetapi saya masih khawatir tentang kemudahan penggunaan spesifikasi API saat ini dengan tautan semantik. API kami terutama akan dikonsumsi oleh pelanggan kami dan beberapa kemitraan pihak ketiga dan kami telah pergi ke REST karena API XML-RPC sebelumnya terlalu sulit bagi konsumen kami.

tl; dr;

Pertanyaan:

Adakah yang menerapkan representasi tautan semantik mengalami masalah konsumen dengan kesulitan?

Pembaruan (21/6): Saya telah memutuskan untuk tetap dengan tautan semantik dan berharap bahwa kebingungan itu merupakan kasus tepi. Saya akan mencoba mengingat untuk menjawab pertanyaan dengan pengalaman kami setelah API terhubung dengan beberapa konsumen.

Edit: tambahkan contoh

JSON Akun Semantik:

{
    "username": "paul",
    "links": [
        {
            "title": "addresses",
            "rel": "related",
            "href": "http://example.com/account/paul/addresses"
        },
        {
            "title": "history",
            "rel": "related",
            "href": "http://example.com/account/paul/history"
        }
    ]
}

XML Akun Semantik:

<account>
    <username>paul</username>
    <link title="addresses" rel="related" href="http://example.com/account/paul/addresses" />
    <link title="history" rel="related" href="http://example.com/account/paul/history" />
</account>

Akun JSON Sederhana:

{
    "username": "paul",
    "addresses": "http://example.com/account/paul/addresses"
    "history": "http://example.com/account/paul/history"
}

XML Akun Sederhana:

<account>
    <username>paul</username>
    <addresses>http://example.com/account/paul/addresses</addresses>
    <history>http://example.com/account/paul/history</history>
</account>
rest semantics Paul
sumber
Bisakah Anda memberi kami contoh konkret tautan semantik asli, dan "elemen string uri yang lebih sederhana"? Tidak terlalu jelas apa yang Anda maksud dengan istilah-istilah itu, terutama yang terakhir.
Tom Anderson
Diperbarui dengan contoh nyata. Saya juga bisa menambahkan contoh untuk daftar / koleksi paginasi juga jika itu membantu.
Paul

Jawaban:

3

Saya lebih suka memiliki:

{
  "username": "paul",
  "address": {
      "rel": "related",
      "href": "http://example.com/account/paul/addresses"
  },
  "history" {
      "rel": "related",
      "href": "http://example.com/account/paul/history"
  }
}

Ini menghilangkan array dan membuat objek dapat dilalui (untuk mendapatkan alamat akun misalnya dalam JavaScript, seseorang dapat mengatakan account.address.href alih-alih menelusuri semua tautan dan menemukan yang terlihat seperti alamat). XML yang Sesuai:

<account>
    <username>paul</username>
    <addresses>
        <link rel="related" href="http://example.com/account/paul/addresses" />
    </addresses>
    <history>
        <link rel="related" href="http://example.com/account/paul/history" />
    </history>
</account>

Bagaimana menurut anda?

Ville Immonen
sumber
1

Impian web semantik adalah tautan dapat ditemukan secara otomatis. Karena bagian yang sulit adalah memahami hubungan dan cara menggunakannya, saya percaya bahwa informasi semantik tidak begitu berguna.

Saya memiliki sedikit condong ke arah bentuk Semantic XML karena atribut "rel" memiliki mekanisme ekstensibilitas bidang-bidang yang dipisahkan ruang, dan "tautan" dipahami dengan baik.

Sebagai konsumen API semacam itu, saya tidak melihat banyak perbedaan lainnya.

Andrew Dalke
sumber