Apa Itu API — Aturan yang Disepakati untuk Bertukar Data dan JSON

Artikel ini membahas API.

API adalah aturan yang disepakati agar program bisa bertukar data satu sama lain.

Kita akan menelusuri tiga bagian pemanggilan dan JSON, format teks yang dikembalikan.

• Apa yang sebenarnya dikirim oleh "memanggil API", dan ke mana
• Tiga bagian pemanggilan — URL, method, response
• Cara membaca key dan value dari JSON yang dikembalikan
• Kode status yang menunjukkan berhasil atau gagal, dan langkah berikutnya untuk tiap angka

"Memanggil API" berarti mengirim request ke URL yang sudah ditentukan dan menerima response

Data cuaca bukan dimiliki oleh programmu sendiri, melainkan oleh server layanan eksternal.

API yang dipanggil dengan request dan response HTTP disebut Web API, dan setiap URL yang diterimanya adalah satu endpoint.

Layanan eksternal bisa menjadi penyedia, begitu juga server my-app.

Dan satu layar pun belum tentu hanya memanggil satu endpoint.

Sebelum halaman muncul, terjadi tiga kali putaran request dan response.

Yang terhubung langsung dengan browser hanyalah server my-app.

Server yang sama menjadi penyedia dari sisi browser, dan menjadi pemanggil dari sisi API cuaca.

Memanggil API berarti mengirim dan menerima

Memanggil API berarti mengirim request ke URL yang sudah ditentukan dan menerima response yang dikembalikan.

Setiap URL itu adalah sebuah endpoint; pemanggilnya bisa browser bisa juga server kamu sendiri, dan penyedianya pun belum tentu layanan eksternal.

Tiga bagian pemanggilan — URL, method, response

Yang tertulis di panduan dan dokumentasi hanya tiga hal.

Ke mana dikirim (URL), apa yang ingin dilakukan (method), dan apa yang dikembalikan (response).

URL sebagai bagian pertama terbagi menjadi dua peran, dengan ? sebagai batasnya.

Bagian setelah ? adalah parameter (query parameter, yaitu syarat data yang kamu inginkan yang ditambahkan di ujung URL dalam bentuk nama=nilai), yang juga ditulis sebagai query parameter.

Bagian kedua adalah method (HTTP method, yaitu kata yang sudah ditentukan seperti GET atau POST yang menunjukkan apa yang ingin dilakukan sebuah request).

Kamu menulisnya di awal baris, dan perilakunya berubah meski dikirim ke URL yang sama.

GET tidak mengubah data di sisi server, tetapi POST mengubahnya begitu dikirim.

Di panduan, hal ini ditulis dengan method dan URL yang berjajar.

Baris yang diawali # adalah penjelasan, dan satu baris di bawahnya adalah cara memanggilnya.

# Mengambil cuaca. Method di depan, URL di belakang (parameter di ujung)
GET https://api.example.com/weather?city=tokyo

# Mendaftarkan 1 pemesanan. URL sama, method beda, perilakunya pun beda
POST https://example.com/reservations

Dokumen yang merangkum cara memanggil ini dan bentuk response yang dikembalikan adalah dokumentasi API (API reference).

Kalau panduan menyebut "lihat dokumentasi API", di sanalah kamu mencari ketiga bagian itu.

Sebelum mengirim, kamu hanya menentukan 2 hal

Sebelum mengirim, yang kamu tentukan sendiri hanya dua: ke mana dikirim dan apa yang ingin dilakukan.

Ke mana dikirim adalah URL, dan bagian sebelum ? adalah endpoint-nya; apa yang ingin dilakukan adalah method. Hanya bagian ketiga, yaitu response, yang tidak bisa kamu tentukan sendiri — kamu membaca apa pun yang dikembalikan.

JSON adalah format teks yang menuliskan data sebagai pasangan key dan value

"JSON yang dikembalikan" di panduan adalah body dari response.

JSON (JavaScript Object Notation, yaitu format yang seluruhnya terdiri dari teks dan menuliskan data sebagai pasangan key dan value) adalah format paling umum yang dipakai untuk body Web API.

JSON yang dikembalikan API cuaca bentuknya seperti ini.

{
  "city": "Tokyo",
  "temp": 23.5,
  "rain": false,
  "forecast": [
    { "day": "mon", "high": 25 },
    { "day": "tue", "high": 22 }
  ]
}

Yang berjajar adalah pasangan key dan value (key / value: nama yang diberikan pada sebuah nilai adalah key, dan isi yang ditunjuk nama itu adalah value).

Pada "temp": 23.5, temp adalah key dan 23.5 adalah value; key dan value dihubungkan dengan :, dan antarpasangan dipisahkan dengan ,.

Pasangan-pasangan berjajar di dalam { }, dan value-nya sendiri bisa berupa [ ] atau { }.

Value keempat adalah array (array, yaitu beberapa nilai yang dijajarkan berurutan di dalam [ ]), dan setiap itemnya kembali dibungkus { }.

{ } dan [ ] bisa disarangkan sampai berapa pun tingkatnya.

Untuk mengambil satu item dari array, kamu menunjuknya dengan angka seperti [0], dan penomorannya dihitung mulai dari 0, bukan dari 1.

Value yang bukan [ ] atau { } ditulis dalam tiga cara, dan kamu membedakannya dari ada tidaknya " ".

Body yang diterima apa adanya masih berupa satu string panjang, jadi menyebut sebuah key tidak akan mengambil value-nya.

Di buku pengantar, kamu mengubahnya lebih dulu menjadi bentuk yang key-nya bisa dibaca dengan satu baris seperti JSON.parse, lalu menunjuk value dengan nama key seperti data.city.

Hanya baris paling bawah yang ejaan key-nya sengaja dibuat salah satu huruf.

Ejaan yang salah tidak memunculkan error, jadi kalau hasilnya undefined, bandingkan dulu ejaannya dengan JSON-nya.

Namanya memuat JavaScript, tetapi format ini dipakai untuk response API karena bahasa apa pun bisa membaca dan menulisnya.

JSON hanyalah jajaran pasangan nama dan isinya

JSON tidak lebih dari jajaran teks yang menuliskan pasangan sebuah nama dan isinya.

Namanya adalah key dan isinya adalah value; saat diterima ia masih berupa satu string panjang, jadi kamu mengubahnya menjadi bentuk yang bisa dibaca per key sebelum mengambil value.

Response tidak selalu berhasil — kode status menentukan apa yang kamu lakukan

API cuaca berjalan di luar programmu sendiri, jadi pemanggilannya bisa saja gagal.

Karena itu response tidak datang hanya berupa body saja.

Lihat satu response yang dikembalikan itu bagian demi bagian.

Tiga digit di depan adalah kode status (status code, yaitu angka yang menunjukkan berhasil atau gagal beserta jenisnya).

Lihat angkanya dulu, dan baca key dari body hanya ketika berhasil.

Angka itu tidak perlu kamu hafalkan ketiga digitnya; digit pertamanya menentukan langkah berikutnya.

Dengan API cuaca yang sama pun, angka yang dikembalikan berubah menurut apa yang kamu kirim dan kondisi penyedianya.

Selain 404, angka 500 dikembalikan ketika terjadi gangguan di sisi penyedia.

404 bukan hanya angka untuk "halaman tidak ada": pada API, angka ini juga dikembalikan ketika tidak ada data yang cocok dengan syarat parameternya.

Kalau kamu memanggil sesuai panduan dan 404 dikembalikan, bandingkan ejaan dan parameternya dengan dokumentasi API.

Di antara angka yang diawali 4, 401 adalah angka untuk saat tidak ada yang menunjukkan siapa pemanggilnya, atau yang ada tidak benar.

Untuk menunjukkan hal itu, kamu melampirkan API key ke request.

Lihat angkanya dulu, baru baca body-nya

Ketika response dikembalikan, lihat angkanya dulu sebelum membaca body.

Kalau diawali 2, body memuat key yang kamu inginkan; kalau diawali 4, perbaiki URL dan syarat yang kamu kirim; kalau diawali 5, tunggu sebentar lalu panggil lagi.