Documentation & Testing API dengan Postman part 2

Ardani Rohman
Mar 21, 2017 · 5 min read

Melanjutkan sesi dari part 1 kita telah membahas bagaimana melakukan request ke API melalui postman kemudian kita bisa simpan request kedalam collection yang bisa dishare ke anggota tim lain. Dipart 2 yang akan kita bahas kali ini adalah

  1. Design API yang Baik
  2. Documentation & Mockup API dengan Apiary
  3. Testing API dengan Postman

Kenapa Design API itu Penting ?

what is an API?

API (Application program interface) adalah service yang menyediakan data dari server yang di request oleh client yang biasanya dalam format json, API ini adalah bagian yang paling penting dalam sebuah aplikasi Mobile / web frontend. Design API yang jelas akan memudahkan kita dalam mendevelop aplikasi.

Bayangkan ketika sebuah API didesign dengan kembalian data yang tidak konsisten, nama path yang tidak merepresentasikan dari fungsi API, data yang dikembalikan terlalu berbelit belit dalam artian seharusnya bisa 1x panggil tapi harus 2x panggil dengan path API yang berbeda itu akan menambah effort untuk developing.

Bagaimana API yang Baik?

  1. Restful

Untuk penamaan path API yang baik kita bisa memperhatikan aturan Restful. Restful ini hanya menjadi acuan, mungkin ada beberapa kondisi tidak bisa menggunakan aturan Restful.

Table Restful API

sebagai contoh ada Restful pada resource admin/post diatas, dengan path yang sama yaitu /admin/posts/ kita bisa membuat beberapa action sesuai dengan HTTP Verb. Untuk nama path yang biasa digunakan adalah plurar (jamak)

2. HTTP Status Code

Http Status code ini berfungsi untuk membantu kita dalam mengenali response balik dari API

untuk menentukan Http Status Code bisa cek flowchart disini http://racksburg.com/choosing-an-http-status-code

3. Error Message

Error message yang baik akan memudahkan developer dalam mengenali kesalahan seperti missing parameter, error parameter validation dll. berikut salah satu contoh error message di twitter

lebih lengkapnya bisa dilihat di doc API twitter

4. Authentication

Authentication ini diperlukan untuk membatasi akses pada API. Karena API bersifat stateless (tidak menggunakan session untuk menyimpan auth) sehingga menggunakan token yang dikirim melalui header request seperti JWT dan OAuth2. untuk implementasi Auth akan kita bahas di artikel berikutnya :)

5. Versioning

Versioning ini digunakan ketika kita mau mengembangkan API ke versi yang baru dan masih support untuk API yang lama. teknik versioning API ada 2 macam yang pertama adalah dengan menambahkan path pada API /v2 (terbaru) dan /v1 (lama) bisa dimanage melalui Route dilevel aplikasi atau di level web server. Cara yang kedua menggunakan param header

content-type :application/vnd.api.v2+json http://www.iana.org/assignments/media-types/application/vnd.api+json

Documentation & Mockup API

Keperluan documentation API tidak kalah penting didalam pengembangan API, documentation API yang lengkap akan mempermudah dalam proses develop aplikasi mobile atau web frontend. Untuk urusan documentation dan mockup sudah ada beberapa service online yang bisa digunakan secara free salah satunya adalah Apiary.io

pada Apiary kita bisa membuat mockup API dan documentation sekaligus, fitur yang dimiliki apiary memungkinkan kita membuat Server Fake API bisa diakses secara public sehingga proses develop tim mobile / frontend tidak perlu menunggu sampai API siap tetapi bisa menggunakan API dari Apiary untuk sementara. (efisien waktu ⏰)

ini adalah sample API mockup yang saya buat bisa langsung di copy paste ke editor apiary atau bisa dicoba http://docs.ecommerceapi3.apiary.io/

sekarang kita coba untuk test mockup API dengan klik switch console untuk mencoba hasil response API, yang perlu diingat adalah mockup API ini bersifat statis jadi format yang kita tulis akan menjadi response dan pastikan response format yang kalian tulis itu valid

console mockup Apiary
response mockup

selain itu kita bisa call langsung url private dari generate apiary https://private-f63cda-ecommerceapi3.apiary-mock.com/categories?page=1&limit=20 dan hasilnya:

response json

Testing API

setelah documentation selesai dibuat saatnya kita bikin testing API. banyak cara untuk testing API bisa melalui unit test memanfaatkan library seperti Codeception / Laravel Dusk tapi kali ini kita bahas yang paling simple menggunakan Postman

sebelumnya kita sudah bikin mockup API di Apiary sekarang kita bikin testnya. Untuk postman kita bisa menggunakan script JS untuk membuat testingnya doc : https://www.getpostman.com/docs/testing_examples

Aktifkan Postman Console pada menu view show postman console untuk keperluan debugging.

variable yang telah disediakan oleh postman adalah request, responseBody, responseHeaders, responseCode bisa langsung console.log untuk melihat isinya.

Test API ini konsepnya adalah membuat membuat perbandingan response code dan struktur json response yang dikeluarkan

untuk menjalankan script test API caranya sama dengan call API lewat postman dan hasilnya bisa dilihat seperti pada tampilan dibawah ini 😀

hasil test API

Dari hasil test API diatas semua pass / success, setelah test yang kita buat sudah sesuai yang diharapkan maka ketika API sudah selesai develop kita bisa menganti environmentnya di postman untuk melakukan test di staging misalnya. Ketika ada perubahan API kita hanya perlu menjalankan test yang sudah kita buat dan apabila success bisa dilanjutkan deploy ke production.

Kesimpulan

API menjadi bagian penting dalam menghubungkan antara backend dengan frontend dan mobile. Kualitas API bisa dilihat dari response body, status code, error message yang dihasilkan. Pastikan ketika develop API kita tidak lupa untuk membuat design dan documentation sebab kebanyakan bottleneck antara backend dan frontend sering terjadi pada API yang tidak jelas. Next kita akan membahas tentang How To Developing API 🎯

Suka artikel ini? Klik ❤ dan follow untuk mengetahui artikel lebih lanjut :D

Artikel yang lain

  1. Dokumentation & Testing API dengan Postman part 1
  2. Dokumentation & Testing API dengan Postman part 2

SkyshiDigital

We help scale up your startup to the next level

Ardani Rohman

Written by

Remote Software Engineer at Agency Analytics. Ready for collaboration 🎯 find me: http://ardani.github.io

SkyshiDigital

We help scale up your startup to the next level

More From Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade