Belajar REST API dari Dasar

Saat aplikasi cuaca di ponselmu menampilkan suhu terbaru, atau situs toko online memperlihatkan stok produk, datanya hampir pasti berasal dari sebuah API. API adalah jembatan yang memungkinkan program berkomunikasi dengan program lain. Memahaminya adalah keterampilan inti bagi frontend maupun backend developer.

Apa itu API?

API (Application Programming Interface) adalah aturan yang mendefinisikan bagaimana satu program meminta sesuatu dari program lain dan dalam format apa jawabannya. Analogi restoran: kamu (klien) tidak masuk dapur; kamu memesan lewat pelayan (API), dan dapur (server) mengirim hidangan lewat pelayan yang sama.

REST (Representational State Transfer) adalah gaya merancang API web yang memanfaatkan HTTP secara konsisten. API yang mengikutinya disebut RESTful.

Fondasi: cara kerja HTTP

Komunikasi terjadi dalam pola permintaan (request) → tanggapan (response).

Request terdiri dari:

• Method: apa yang ingin dilakukan.
• URL: sumber daya mana.
• Header: metadata (format, token).
• Body (opsional): data yang dikirim.

Response terdiri dari:

• Status code: berhasil atau tidak.
• Header dan body (biasanya JSON).

Contoh nyata:

GET /api/produk/7 HTTP/1.1
Host: contoh.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 7, "nama": "Pensil 2B", "harga": 2500 }

Konsep utama REST

1. Resource (sumber daya) dan URL

Semua dipandang sebagai benda yang diidentifikasi URL, memakai kata benda jamak:

Hindari kata kerja di URL (/ambilProduk); biarkan method HTTP yang menyatakan aksinya.

2. Method HTTP

Idempoten berarti memanggil berkali-kali memberi efek akhir yang sama. DELETE /produk/7 dua kali: produk tetap terhapus. Namun POST dua kali bisa membuat dua data.

GET tidak boleh mengubah data (safe), supaya aman di-cache dan tidak terpicu oleh crawler.

3. Kode status

Bedakan 401 (belum terautentikasi / token salah) dan 403 (sudah login tetapi tidak punya hak).

4. Stateless

Setiap permintaan harus membawa semua informasi yang dibutuhkan (misalnya token autentikasi). Server tidak menyimpan "ingatan" tentang klien di antara permintaan. Ini memudahkan penskalaan karena permintaan bisa dilayani server mana pun.

5. Representasi: JSON

Data dipertukarkan dalam bentuk teks, kini hampir selalu JSON:

{
  "id": 7,
  "nama": "Pensil 2B",
  "harga": 2500,
  "tersedia": true,
  "kategori": { "id": 2, "nama": "Alat Tulis" },
  "tag": ["murah", "sekolah"]
}

Tipe JSON: string, angka, boolean, null, array [], dan object {}. Kunci selalu memakai tanda kutip ganda, dan tidak boleh ada koma di akhir.

Klien memberi tahu format dengan header Accept: application/json (yang diinginkan) dan Content-Type: application/json (yang dikirim).

Mencoba langsung dengan curl

Layanan latihan gratis seperti jsonplaceholder.typicode.com aman untuk bereksperimen.

# Baca daftar
curl https://jsonplaceholder.typicode.com/posts?_limit=2

# Baca satu
curl https://jsonplaceholder.typicode.com/posts/1

# Buat baru
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Halo","body":"Isi","userId":1}'

# Lihat header dan status
curl -i https://jsonplaceholder.typicode.com/posts/1

Memanggil API dari JavaScript

async function ambilPost(id) {
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);

  if (!res.ok) {                      // fetch TIDAK melempar error untuk 404/500
    throw new Error(`Gagal: ${res.status}`);
  }

  return res.json();
}

ambilPost(1).then(console.log).catch(console.error);

Mengirim data:

await fetch('/api/produk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
  body: JSON.stringify({ nama: 'Pensil', harga: 2500 }),
});

Perhatikan: fetch hanya menolak promise untuk kegagalan jaringan; status 404/500 tetap dianggap "berhasil", jadi selalu periksa res.ok.

Autentikasi API

API publik sering memerlukan identitas:

Aturan: selalu gunakan HTTPS, jangan menaruh rahasia di URL, dan jangan menanam kunci rahasia di kode frontend yang bisa dilihat siapa pun.

Pagination, filter, dan sorting

Mengembalikan jutaan data sekaligus tidak mungkin. Konvensi umum lewat query string:

GET /produk?page=2&per_page=20
GET /produk?kategori=alat-tulis&harga_min=1000
GET /produk?sort=-harga          (tanda minus = menurun)

Respons biasanya menyertakan metadata: total, halaman saat ini, dan tautan halaman berikutnya.

Menangani error dengan baik

Error yang baik memuat kode status yang benar dan pesan yang bisa ditindaklanjuti:

HTTP/1.1 422 Unprocessable Entity

{
  "message": "Data tidak valid.",
  "errors": { "harga": ["Harga harus berupa angka."] }
}

Klien dapat menampilkan pesan per kolom tanpa menebak.

REST bukan satu-satunya

Latihan

1. Gunakan curl -i pada https://jsonplaceholder.typicode.com/posts/9999. Apa status yang kamu dapat dan apa artinya?
2. Tulis fungsi JavaScript yang mengambil 5 post pertama dan menampilkan judulnya.
3. Rancang URL dan method untuk API perpustakaan: daftar buku, detail buku, pinjam buku, kembalikan buku, riwayat peminjaman anggota.
4. Buat API sendiri: ikuti Membuat REST API dengan Laravel.

Kesimpulan

REST API menyatukan beberapa gagasan sederhana: resource sebagai URL, method HTTP sebagai aksi, kode status sebagai hasil, JSON sebagai format, dan stateless sebagai prinsip. Setelah ini kamu siap membangun API sendiri, dan membaca dokumentasi API apa pun akan terasa jauh lebih mudah. Selanjutnya, pelajari praktik terbaik di Tips Membuat API dengan Laravel.