Pengujian dan Dokumentasi API dengan Postman, Bagaimana caranya??

Halo sahabat coders, sudah ga sabar yaa dengan materi kali ini?😁

Kemarin kita sudah belajar tentang Eloquent beserta ORM, cara menghindari N+1 problem, dan sebagainya. Tentunya mereka sangat wajib untuk para sobat pelajari karena berguna banget untuk meningkatkan performa aplikasi (load data lebih cepat, menghindari lagging, dan kelancaran server menerima request). Cekidott yang mau belajar atau flashback pertemuan sebelumnya bisa akses link berikut *https://medium.com/amcc-amikom/eloquent-orm-relationship-89076912b773*

Pada artikel kali ini kita bahas tentang bagaimana cara membuat dokumentasi API dengan menggunakan tools Postman.

Yukk kita bahas….😉

Topik yang dibahas

· Topik yang dibahas · Apa dan mengapa penting membuat dokumentasi API? · Apa itu Postman? · Komponen penting pada Postman · Praktik Membuat Dokumentasi API · 0. Penjelasan Project Laravel · 1. Setup awal postman · 2. Membuat Collection · 3. Buat Environment untuk Workspace · 4. Menguji dan Buat Dokumentasi API · a. Uji dan buat dokumentasi endpoint Get All Notes [GET] · b. Uji dan buat dokumentasi endpoint Get Notes by Id [GET] · c. Uji dan buat dokumentasi endpoint Login [POST] dan bagaimana cara menyimpan token yang dihasilkan secara otomatis · d. Uji dan buat dokumentasi endpoint create Notes [POST] · Publish Dokumentasi API

Apa dan mengapa penting membuat dokumentasi API?

Tentu sangat penting bagi seorang Backend-ers untuk membuat dokumentasi API yang dibuatnya. Karena dengan adanya dokumentasi API, developer lain seperti frontend developer, mobile developer, dan pihak terkait mengetahu API yang sobat Backend-ers buat (Bagaimana cara menggunakan API tersebut, parameter apa yang perlu diisi, untuk apa API tersebut digunakan). Selain itu, kegunaan lainnya adalah:

• Mempermudah developer untuk menggunakan API.
• Meningkatkan efisiensi tim, dapat bekerja dengan efisien karena frontend tak perlu bertanya-tanya banyak kepada backend.
• Mempercepat integrasi.
• Mengurangi kesalahan dalam menggunakan API sehingga pembuatan aplikasi bisa menjadi lebih cepat.
• Mendukung pemeliharaan & skalabilitas.

Apa itu Postman?

Logo Postman

Postman adalah tools dan software yang digunakan untuk membuat dokumentasi API. Selain itu sebenarnya fungsi dari postman adalah

• Membuat dokumentasi API, mendokumentasikan API, termasuk detail endpoint, parameter, jenis data yang diharapkan, dan contoh permintaan/respons.
• Menguji API, melakukan pengujian API dengan berbagai method (POST, GET, DELETE, UPDATE/PATCH)
• Membuat Mock API, membuat server tiruan untuk mensimulasikan response API
• Berkolaborasi dengan tim, postman mendukung kolaborasi pembuatan dokumentasi api bersama tim

Nah pada materi kali ini kita fokus dalam proses pembuatan dokumentasiAPI aja ya gaes, karena kalau kita bahas semuanya malah jadi e-book hehehe😶

Komponen penting pada Postman

Lingkungan kerja postman

Gambar diatas merupakan antarmuka lingkungan kerja postman, artinya ketika temen-temen menggunakan postman, seperti itulah tampilannya.

Pada lingkungan kerja tersebut terdapat komponen-komponen penting yang wajib temen-temen ketahui dan pahami:

• Workspace: ruang kerja tempat kamu mengelola dan mengelompokkan semua koleksi request, environment, dokumentasi, dan tim kamu.
• Collection: kumpulan request yang dikelompokkan berdasarkan fitur, modul, atau endpoint API tertentu.
• Folder: tempat beberapa pengujian API disimpan
• Request: tempat setting pengujian API
• Environment: kumpulan variabel konfigurasi untuk membantu dalam pengujian API

Praktik Membuat Dokumentasi API

Langsung aja teman-teman kita praktik membuat dokumentasi API dengan Postman.

Pertama-tama, persiapkan:

• Postman (*https://www.postman.com*): pastikan kamu sudah membuat akun postman
• Project laravel (https://github.com/amccamikom/amcc-web-backend-2025/tree/pertemuan-10)
• Koneksi internet: postman memerlukan koneksi internet untuk login
• Database MySQL
• Laragon: buat njalanin laravel

Jika sudah, yuk langsung kita cobaa..

0. Penjelasan Project Laravel

Project laravel yang saya berikan terdapat beberapa API yang sudah ada. Berikut teman-teman bisa akses di link ini ya

***Link List API Note App***

1. Setup awal postman

Pertama, buka terlebih dahulu postman temen-temen, lalu akan tertampil seperti ini

Antarmuka beranda postman

selanjutnya buat workspace, dengan klik Workspace yang terletak dikiri tengah. Lalu, akan tertampil seperti ini…

Setelah tekan Create lalu pilih Internal karna projek kali ini kita mau gunakan sendiri lanjut tekan Blank workspace, karena kita mau buat manual sendiri pengaturan dan tata letak dokumentasi API kita.

Klik Create Workspace, isikan nama workspace, misal: Note App. Pilih tipe workspace dengan *Internal jadi sifatnya nanti private, hanya bisa diakses oleh pembuat atau tim yang terdaftar. Pilih manage access nya adalah Only you and invited people. *Klik Next

Maka akan tertampil seperti ini di halaman utama workspoce yang berhasil dibuat.

2. Membuat Collection

Selanjutnya kita buat collection untuk menyimpan dokumentasi API kita secara lebih khusus. Pada aplikasi kita Note App yang pertama kita akan membuat Authentication terlebih dulul.

Klik icon Plus , pilih blank collection , isikan nama collection nya, yaitu Authentication.

Maka hasilnya begini…

3. Buat Environment untuk Workspace

antarmuka halaman pembuatan environment

• Ikuti seperti digambar
• buat environment baru, berikan nama Note App Env

• no.1. Isikan variebel base_url (url utama kita) dan token (untuk menyimpan data token authentikasi)
• no.2. Pilih pemilihan env ke Note App Env

4. Menguji dan Buat Dokumentasi API

Lalu kita lakukan uji api yang telah dibuat, uji API ini juga merupakan bagian dari dokumentasi api. Buat API kok ga diuji dulu?? 😶

Buat request baru di collection customers. Disini kita buat dokumentasi untuk endpoint Authentikasi dan Category.

a. Uji dan buat dokumentasi endpoint Get All Notes [GET]

• no.1. Buat Collection baru kasi nama Notes dan klik tan + disamping logo bintang.
• no.3. Isikan url endpoint dengan menggunakan variabel base_url
• no.4. Klik Send, lalu muncul hasil dari api tersebut.

Lalu buat example request untuk dokumentasi hasil response dari api yang telah kita uji

• no.1. buat example baru dengan mengeklik kanan request Get All Category.
• no.2. berikan nama 200 Success (200: status code, Success: messagenya) karena response kita tadi success.
• no.3. ubah tipe response menjadi JSON
• no.4. status code nya disesuaikan menurut response tadi, yaitu 200 OK

Tak hanya untuk yang response nya sukses (code 200), untuk response yang gagal juga sobat tambahkan example nya yaaa…(code ≥ 400 atau code ≥ 500)😉

Semakin lengkap, semakin baikk

b. Uji dan buat dokumentasi endpoint Get Notes by Id [GET]

antarmuka uji endpoint Get category by id

• no.1. Buat request baru bernama Get Notes by Id
• no.2. Disini kita mengguakan Path Variable (Sebuah variabel untuk path dalam url). Gunakan ‘:’ untuk memulai menggunakan path variabel
• no.3. Berikan nama, value dan deskripsinya

Selanjutnya buat, example nya untuk status code 200 (success) dan 404 (category tidak ditemukan)

c. Uji dan buat dokumentasi endpoint Login [POST] dan bagaimana cara menyimpan token yang dihasilkan secara otomatis

Sesuai dengan penjelasan sebelumnya mengenai API, untuk menguji endpoint POST Category, DELETE Category, dan PUT/PATCH Category, diperlukan token autentikasi yang diperoleh melalui endpoint Login. Token ini hanya diberikan kepada pengguna yang berhasil login.

• no.1. Buat folder auth (untuk menyimpan request tentang autentikasi), beserta buat request endpoint login.
• no.2. Pilih method POST dan isikan url nya sesuai dari list api yang telah dibagikan
• no.3. Karena method POST, maka diperlukan body (data) untuk kita kirimkan ke server.
• no.4. Pilih raw karena hanya mengirim data teks.
• no.5. Disini kita kirimkan data email dan password.
• no.6. Klik Send untuk menguji.
• no.7. Response nya tertampil, dan bisa kita lihat ada property access_token, nah si property inilah yang kita simpan nantinya.

Hasil dari response endpoint login ini terdapat token yang disertakan. Token tersebut perlu kita simpan di variabel token yang telah kita buat di environment. Token ini berfungsi sebagai kunci untuk mengakses endpoint yang memerlukan autentikasi.

Bagaimana caranya? Yukk kita bahas….

• no.1. Klik Scripts untuk mulai menggunakan script
• no.2. Klik Post-response karena script yang kita gunakan ini untuk response dari api.
• no.3. Isikan sesuai code diatas.

// ambil response api nya
const res = pm.response.json();
// set variabel token dengan nilai dari propery access_token
// * menggunakan access_token sesuai dengan property response login
pm.environment.set('token', res?.access_token);

Uji lagi endpoint login, maka token nya otomatis tersimpan di environment token.

Jangan lupa untuk membuat example nya juga yaaa…

d. Uji dan buat dokumentasi endpoint create Notes [POST]

Oke, disini sekarang kita mau mencoba untuk membuat Notes baru sekarang pada collection Notes buatlah request baru yang bernama Create Notes, nah dikarnakan user tidak bisa membuat note baru tanpa login maka user harus login dulu, nah disini kita harus menyimpan tokenya dulu.

• no.1. Buat request baru yang bernama Create Notes
• no.2. Di Auth Type Pilih Bearer Token
• no.3. Token Automatis tersisi di colom di kanan

Nah jika token udah berhasil muncul, sekarang isi rawnya seperti yang udah kita praktekan tadi, jangan lupa untuk methodnya POST yaa…

Publish Dokumentasi API

Setelah semua pengujian dan dokumentasi selesai disusun di Postman, langkah selanjutnya adalah mempublikasikannya. Tujuannya agar dokumentasi tersebut dapat diakses oleh seluruh anggota tim dengan mudah, tanpa perlu mengirim file satu per satu.

Dengan memanfaatkan fitur Public Documentation dari Postman, sobat bisa membagikan link dokumentasi yang berisi detail endpoint, parameter, contoh request-response, hingga environment yang digunakan. Cara ini sangat membantu untuk kolaborasi tim dan mempercepat proses integrasI.

Bagaimana caranya? Cekidottt teruskan baca artikel ini yaaa….

• no.1. Klik collection Authentication
• no.2. Klik view complete documentation untuk melihat detail dokumentasi

no.1. Di halaman ini, sobat bisa mengisi berbagai detail penting dari API. Mulai dari penjelasan umum setiap endpoint, hingga deskripsi lebih rinci untuk masing-masing elemen. Beberapa hal yang bisa sobat lengkapi, antara lain:

• Penjelasan setiap endpoint, seperti fungsinya, kapan digunakan, dan siapa yang boleh mengakses.
• Deskripsi setiap properti pada body request, agar developer lain paham struktur data yang dibutuhkan.
• Penjelasan umum untuk setiap API, seperti tujuannya, autentikasinya, serta skenario penggunaan.

Semakin lengkap dokumentasi yang sobat buat, maka akan semakin mudah bagi tim lain (atau diri sendiri di masa depan) untuk memahami dan menggunakan API dengan benar.

no.2. Sobat bisa klik Publish jika sudah siap.

Masih ada praktik untuk endpoint metode PUT/PATCH dan DELETE. Cara penggunaannya serupa dengan GET dan POST, hanya berbeda pada jenis metodenya saja.

Cukup segini saja ya teman-teman kita belajar bagiamana cara menguji dan membuat dokumentasi API menggunakan Postman.

Software untuk membuat dokumentasi API tak hanya Postman tapi ada juga Swagger, Thunder Client, Insomnia, Katalon, Apidog, dan masih banyak lagi.