REST API , REST API Everywhere

– Toy Story meme ..

Dimana-mana orang akan berbicara mengenai API, terutama REST API ketika melakukan integrasi dengan aplikasi lain, ataupun didalam organisasi internal sendiri.

REST API (Application Programming Interface) menjadi perekat antara aplikasi Frontend, mobile, cloud, dengan service backend, cloud, dan aplikasi lain.

Aplikasi yang dibuat dengan Angular, perlu spesifikasi REST API ketika ingin mengambil data stok barang dari backend.

Begitu pula ketika aplikasi Flutter ingin melakukan otentikasi pengguna, maka diperlukan REST API OAuth2 untuk prosesnya.


Lalau Permasalahannya ?

Dengan banyaknya API yang kita atau orang lain punyai, maka akan ada kesulitan didalamnya, yaitu :

  • bagaimana mengelola API tersebut.
  • bagaimana mendokumentasikan API tersebut, baik ketika baru saja membuat API tersebut, atau ketika ada yang berubah dari API tersebut.

Sekarang akan kita bahas mengenai point ke 2, yaitu mendokumentasikan API.

Mendokumentasikan API ini bukanlah hal yang mudah.

Hal ini karena :

  • harus ada kesepakatan mengenai terminologi dokumentasinya yang dipahami oleh hampir semua orang yang terlibat.
  • harus jelas, lengkap dan terstruktur.
  • harus mudah juga diubah dokumentasinya ketika terjadi perubahan API nya.
  • untuk tahapan lebih lanjut, mesti bisa digunakan juga untuk validasi API, integrasi API secara otomatis.

Membuat dokumentasi dalam file .README, .txt, atau .doc, .docx tentunya bukan pilihan yang tepat.

Karena mudah dibuat di awal, akan tetapi tidak mudah untuk diubah ketika API nya juga berubah.

Dokumentasi nya juga terpisah dari code program yang kita punyai, sehingga kemungkinan terjadinya ketidak sinkronan antara code dan dokumentasi bisa sangat mungkin terjadi.

Misalnya, ketika code yang kita ubah perlu perubahan cepat, sehingga lupa untuk mengubah dokumentasinya.


Apa lagi masalahnya ?

Masalah waktu yang dihabiskan untuk melakukan dokumentasi.

Membuat dokumentasi dimana-mana butuh waktu.

Oleh karena itu ada nama nya profesi Technical Writer, Software Requirement Spesification, atau juga ada Software Technical Specification.

Begitu pula dengan REST API.

Mau tak mau harus ada waktu yang dikorbankan untuk bisa membuat dokumentasi terhadap REST API yang kita buat.

Nah sekarang tentunya kita tidak mau menghabiskan waktu berharga kita untuk dokumentasi REST API saja.

Muncullah ide agar kita bisa menghemat waktu , tetapi tetap dengan otomatis membuat dokumentasi yang sinkron dengan code REST API yang kita buat.


Lalu ?

Tentu saja dengan membuat tools dong…!

Bagaimana kalau kita membuat sebuah tools yang secara otomatis menggenerate dokumen yang mempunyai standar yang bagus dalam dokumentasi, dan dokumentasinya ini juga mudah dipahami.

Sasarannya tentu saja bukan hanya manusia sebagai pembaca spesifikasi REST API nya tersebut, akan tetapi juga mesin atau komputer lain yang menggunakannya.

sebagaimana kata pepatah :

Sekali merengkuh dayung, dua tiga pulau terlampaui

begitu pula mestinya tools yang kita butuhkan ini.

Mestinya tools ini bisa menggenerate dokumentasi yang kemudian bisa kita validasi dari sisi client (pihak yang menggunakan REST API tersebut) dan otomatis oleh komputer tersebut, dan bisa juga melakukan generate stub/kerangka code sederhana untuk melakukan koneksi ke REST API tersebut.

Hmmm…mestinya menarik ini kaan..

Biar lebih bisa diadopsi oleh banyak orang, maka yang perlu dibuat bukan hanya implementasi dari tools nya ini saja.

Akan tetapi yang lebih penting lagi adalah spesifikasinya.

Dengan spesifikasi, maka akan ada standar dokumentasi yang jelas, lengkap, terstruktur yang menjadi dasar dari implementasi tools ini.

Dengan spesikasi, maka implementasinya juga bisa sinkron antar banyak perusahaan, orang, developer, dan pihak lain yang terlibat.

Disitulah muncul banyak spesifikasi dokumentasi REST API :

  • RAML
  • OpenAPI
  • API Blueprint
  • JSON Api
  • dll.

Oke sekarang kita akan membahas mengenai OpenAPI saja dulu..

Next artikel yaa.

Kita lanjut di Part 2