Pengalaman membuat format API yang konsisten dan mudah dibaca

Entah kenapa sampai saya ingin menulis artikel tentang API. Pengalaman bekerja dengan programmer yang membuat API untuk saya pakai di salah satu project membuat saya ingin sekali menyampaikan betapa API yang konsisten dan mudah dibaca oleh programmer lain (response data) itu sangat-sangat mempercepat kerja dalam menyelesaikan project.

Sebelumnya, mungkin bisa tonton dulu apa itu API di dunia programming lewat video ini.

Yap, jika sudah menonton video tersebut anda akan mengatahui bahwa API itu dipakai oleh banyak aplikasi lain. Simplenya, anda membuka detik.com di website dengan membuka aplikasi detik.com di android ataupun di IOS pasti ada API yang melayani. Lajut ya 🙂

Format Api yang konsisten

Maksudnya apa konsisten? Konsisten disini adalah konsisten dalam menuliskan aturan API. Contoh sederhana adalah API yang membutuhkan parameter-parameter tertentu, baik saya contohkan ambil data artikel di detik.com dengan kategori sepakbola. “sepakbola” adalah parameter untuk mendapatkan artikel melalui API. Sepakbola ini pasti memilik ID ataupun identifier baik berupa integer ID ataupun string Slug. Tulislah parameter-parameter dengan jelas, kapan dia berupa ID atau berupa string.

Contoh kasus yang saya alami lagi adalah ketika menerima response balikan dari API. Kita tahu API pasti memiliki format apakah request yang kita harapkan diterima atau tidak. Misalnya saya ingin mencari artikel dengan kategori “sepakbola”, lalu saya kirim request ID sepakbola misalnya 3, Response yang saya dapatkan misalnya seperti kode dibawah ini.

{
    status: '00',
    msg: 'ok',
    data: [
      {
        'id': 1,
        'title': 'Arsenal seri dikandang PSG',
        'description': 'ini description'
      },
      {
        'id': 3,
        'title': 'Barca bantai Celtic',
        'description': 'barca'
      }
    ]
}

Terlihat, saya ada response format seperti diatas:

  • status: status disini adalah status API menerima atau menolak, kadang status ini juga untuk membedakan apakah request yang diminta memiliki data atau tidak.
  • msg: singkatan dari ‘message’ sengaja dipendek karena memang sudah biasa dalam API. biasa digunakan untuk informasi response dari API.
  • data: Nah ini adalah data yang dikeluarkan oleh API, data ini tergantung dari status, jika status ditolak, otomatis data ini kosong, jika status kosong dalam artian ketika request yang diminta diterima tapi data yang diminta tidak ada alias kosong, maka data akan kosong.

Sebenarnya tidak cuma 3 variable saja dalam API ini, dan kadang formatnya pun berlainan tapi tidak terlalu jauh berlainannya.

Contoh response format yang datanya kosong seperti dibawah ini:

{
  status: '04',
  msg: 'not found',
  data: []
}

Format diatas terlihat, status berbeda dengan status saat diterima. status ini akan digunakan oleh programmer lain untuk mengkondisikan response yang diterima API seperti apa.

Dari sisi penerima/client atau disebut sebagai pemakai API, data ini diakses via PHP seperti ini.

$api_post['category_slug']='sepakbola';
$api_result = $this->post_data('master', $api_post);
$api_result = json_decode($api_result);
if($api_result->status == '00') { # data diterima
     $result = $api_result->data;
} else { # data tidak diterima
     $result = array();
}

json_encode($result);

Format ini sederhana ya, jika status 00 terima, ambil data lalu keluarkan result. Jika status tidak 00 maka set result kosong.

Lalu berikut adalah response dari API yang tidak konsisten ketika data not found

[
  {
    "status": "04",
    "msg": "Data not found"
  }
]

Terlihat diatas, format ini adalah format Array lalu didalam array terdapat object status dan msg. Sedangkan jika kita ke atas, format data diterima dengan baik adalah berupa object.

{
    status: '00',
    msg: 'ok',
    data: [
      {
        'id': 1,
        'title': 'Arsenal seri dikandang PSG',
        'description': 'ini description'
      },
      {
        'id': 3,
        'title': 'Barca bantai Celtic',
        'description': 'barca'
      }
    ]
}

Sekarang bagaimana programmer menggunakan API tersebut karena perbedaan format dan tidak konsisten?
Berikut kode handle nya.

$api_post['category_slug'] = 'sepakbola';
$api_result = $this->post_data('master', $api_post);
$api_result = json_decode($api_result);
if( ( isset($api_result['status']) and $api_result['status'] == '00' ) OR ( isset($api_result[0]['status']) and $api_result[0]['status']=='00' ) ) {
    $result = $api_result->data;
} else {
    $result = array();
}

return response()->json($result, 200);

Lihat lebih panjang lagi kan? Ini tidak bagus untuk penerima response dari API. Karena saya yakin pengguna API tidak hanya programmer PHP saja yang menggunakan tapi mungkin nanti Android atau IOS.

Jika anda tahu, semakin panjang kode, semakin membuat proses lama maka semakin pemakai aplikasi menjadi tidak nyaman. Sekarang kalau buka di Android atau IOS, dengan kondisi aplikasi lama response nya, gak lama aplikasi pasti akan di uninstall.

Oleh karena itu, konsep minimalkan kerja client penerima API ini harus dipikirkan oleh Programmer API.

Response API sulit dibaca

Sulit dibaca ini maksudnya adalah client atau penerima/pengguna API sulit untuk membaca API. Berikut saya contohkan beberapa response yang sulit dibaca.

{
  "id": "1",
  "firstname": "Budiman",
  "lastname": "",
  "email": "budiman@gmail.com",
  "password": "",
  "phone": "021882912819",
  "dob": "1989-08-03",
  "register_time": "0000-00-00 00:00:00",
  "is_active": "0",
  "total_point": "0",
  "point_expired": "0000-00-00",
  "created_at": null,
  "updated_at": null,
  "billing": {
    "BCA": {
      "billing_name": "BCA",
      "billing_account": "BCA Atas Nama Budiman",
      "billing_code": "9182991821234",
      "billing_note": "",
      "is_default": "1"
    },
    "BCA Kantor": {
      "billing_name": "BCA Kantor",
      "billing_account": "BCA Atas Nama PT Purdiantara",
      "billing_code": "918828124123",
      "billing_note": "",
      "is_default": "0"
    }
  },
  "alamat": [
    {
      "id": "1",
      "address_name": "Alamat Rumah",
      "address": "Jl Testing aja",
      "postal_code": "17281",
      "city_id": "3",
      "city_name": "Bekasi Kabupaten",
      "province_id": "9",
      "prov_name": "JAWA BARAT"
    },
    {
      "id": "2",
      "address_name": "Alamat Kantor",
      "address": "jl ampera",
      "postal_code": "17111",
      "city_id": "2",
      "city_name": "Bekasi Kota",
      "province_id": "9",
      "prov_name": "JAWA BARAT"
    }
  ],
  "err_code": "00",
  "message": "OK"
}

Coba kita mau ambil data “alamat” bagaimana caranya? Gampang ya, tinggal ambil key alamat, lalu looping saja data alamat ini karena bentuknya adalah array.

Lalu coba bagaiaman kita mengambil data “billing”? Saya jujur tidak bisa mengambil data format billing. Gak seragam dan gak biasa ya. Sebenernya bisa saja tapi pasti butuh custom code yang tidak biasa yang ujung-ujungnya membuat kode semakin panjang dan response time menjadi besar.

Jadi, buatlah response yang mudah dibaca oleh programmer lain. Bukan format yang aneh-aneh dan sulit ditranslate kembali oleh programmer client.

Ada yang bertanya, jadi mesti pakai Array atau Object?

Tergantung juga, lihat data jika lebih dari satu pakai Array agar programmer lain tinggal looping saja array yang ada. Object biasanya digunakan untuk data yang hanya 1 row.

Sama aja kok array atau object?

Beda gan, sekarang kalo datanya banyak tapi dibuat object pasti tidak bisa kan?

Lalu sekarang jika data pasti hanya 1 row tapi dibuat menjadi array agak ribet juga memanggilnya. Jadi panggilnya mesti $data[0]->namaobject. Ga rapih kan?

Saya ada lagi contoh response seperti ini.

{
  "0": {
    "id": "79",
    "cust_id": "4",
    "product_id": "14",
    "product_name": "Rendang Large",
    "product_qty": "1",
    "product_price": "55000",
    "product_type": "product",
    "product_weight": "200",
    "product_estimasi": "3",
    "total_price": "55000",
    "date": "2016-09-17",
    "last_update": "2016-09-17 13:36:30"
  },
  "1": {
    "id": "80",
    "cust_id": "4",
    "product_id": "2",
    "product_name": "test",
    "product_qty": "5",
    "product_price": "100",
    "product_type": "2",
    "product_weight": "1",
    "product_estimasi": "12",
    "total_price": "500",
    "date": "2016-09-17",
    "last_update": "2016-09-17 16:00:38"
  },
  "total_item": 2,
  "jumlah_item": 6,
  "total": 55500,
  "percent_tax": "10%",
  "tax_price": 5550,
  "total_cart": 61050,
  "err_code": "00",
  "message": "OK"
}

Coba ada yang bisa cara ambil data product seperti response diatas? Anggap object “total_item” tidak ada. Sekarang bagaimana cara ambil data product tersebut? Ribet ya? bagaimana kita tau data ada 2, data lebih dari 2 atau data tidak ada sama sekali?

Thats the point. Buat response yang mudah dibaca oleh programmer lain. Coba bayangkan response yang anda buat anda pakai sendiri.

Jadilah programmer yang baik dan terbuka terhadap perubahan dan masukan dari programmer lain. Jangan mengedepankan EGO. Pikirkanlah project yang kita buat bisa dipakai nyaman oleh Klien kita.

Mudah-mudahan bermanfaat ya 🙂

2 thoughts on “Pengalaman membuat format API yang konsisten dan mudah dibaca”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.