Merancang Web API yang Mudah Dieksplorasi

Meningkatnya jumlah aplikasi software (App) pada berbagai macam perangkat komputasi tentu memerlukan layanan dari berbagai sumber (Verborgh et al, 2015). Sebagai contoh, layanan Facebook API menyediakan layanan untuk melakukan sign in ke dalam sebuah App tanpa mengharuskan pengguna untuk melakukan pendaftaran baru ke dalam App. App akan mengkonsumsi layanan Facebook API untuk melakukan authentikasi dan izin untuk mendapatkan beberapa data dari Facebook untuk digunakan pada App. Facebook API adalah salah satu contoh dari berbagai jenis Web API yang tersedia di Web dan dapat dikonsumsi oleh berbagai client App.

Web API adalah sebuah software yang menyediakan layanan (fungsi-fungsi) spesifik yang dapat dipanggil melalui Web oleh berbagai jenis software lain. Web service adalah salah satu bentuk dari tradisional Web API, umumnya terdapat kontrak berupa sebuah dokumen Web Service Definition Language (WSDL) yang berisi fungsi-fungsi apa saja yang dapat dipanggil dan dieksekusi oleh Web service tersebut. Perkembangan selanjutnya adalah arsitektur REST (Representational State Transfer) API yang diperkenalkan oleh Fielding dan Taylor (2002). Sampai saat ini REST API sangat populer dan diimplementasikan pada banyak Web API.

Mengapa REST API menjadi lebih superior dibandingkan dengan Web service tradisional? Menurut Verborgh et al (2015), API yang mengikuti prinsip REST adalah “native Web citizens” ini berarti API tersebut bekerja sesuai dengan prinsip kerja Web. Fielding dan Taylor (2008) menyebutkan bahwa REST mempunyai beberapa prinsip fundamental sebagai berikut:

  1. Berorientasi pada resource dan addressability
    Seluruh bit informasi harus dibungkus dalam sebuah resource yang dapat diakses melalui penanda yang stabil. Penanda ini disebut dengan URL dan resource diakses melalui HTTP.
    Contoh:
    URL endpoint utama:
    https://api.example.com/
    URL kumpulan resource pengguna:
    https://api.example.com/user
    URL resource pengguna spesifik dengan ID 1001:
    https://api.example.com/user/1001
    URL kumpulan buku milik pengguna spesifik dengan ID 1001:
    https://api.example.com/user/1001/book
     
  2. Penggunaan interface yang seragam
    Arsitektur REST memiliki interface yang seragam untuk dapat mengakses sebuah resource dari URL. Interface ini disebut dengan HTTP verbs yang dijabarkan pada tabel berikut:

    HTTP Verb Deskripsi
    GET Mengambil sebuah representasi resource
    HEAD Mengambil informasi header resource
    OPTIONS Mengambil daftar verbs yang didukung oleh resource ini
    PUT Mengganti resource
    DELETE Menghapus resource
    PATCH Memperbaharui state dari resource
    POST Membuat resource
  3. Representasi resource dan tipe media
    Resource yang direpresentasikan dapat menyesuaikan dengan kemampuan client, contoh HTML, XML, atau JSON.
     
  4. Hypermedia as the Engine of Application State (HATEOAS)
    Resource harus memiliki hyperlink atau form, untuk berpindah ke state aplikasi berikutnya dan menampilkan resource yang berbeda.

REST API yang memanfaatkan prinsip HATEOAS memiliki keuntungan bagi software developer. Sebuah REST API memiliki satu endpoint utama (URL) yang dapat diakses, selanjutnya dapat dieksplorasi seperti halnya melakukan browsing pada Web. Resources dapat dengan mudah ditelusuri dan ditemukan melalui hyperlinks, serta juga dapat dimanipulasi dengan menggunakan HTTP verbs (Amundsen, 2010).

Demikian sekilas mengenai teori dan prinsip terkait perancangan Web API yang mudah dieksplorasi. Pada artikel selanjutnya akan dibahas lebih lanjut mengenai implementasi dari arsitektur REST API memanfaatkan prinsip HATEOAS.

Referensi:

Amundsen, M. (2010, May 31). H Factor: Hypermedia Types. Retrieved Jan 20, 2014, from Amundsen: http://www.amundsen.com/hypermedia/hfactor/

Fielding, R. T. 2008. REST APIs must be hypertext-driven. Untangled – Musings of Roy T. Fielding. from: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Fielding, R. T. and Taylor, R. N. 2002. Principled design of the modern Web architecture. Transactions on Internet Technology 2, 2 (May), 115–150.

Gamache, P. (2014). Pragmatic Hypermedia: Creating a Generic, Self-inflating API Client for Production Use. Proceedings of the 23rd International Conference on World Wide Web (pp. 931-936). Seoul: ACM.

Verborgh, R., Arndt, D., Van Hoecke, S., De Roo, J., Mels, G., Steiner, T., & Gabarro, J. (2017). The pragmatic proof: Hypermedia API composition and execution. Theory and Practice of Logic Programming, 17(1), 1-48.

++++++++++

Photo by Tran Mau Tri Tam on Unsplash

Herru Darmadi