URL & Endpoint — API — Hyper Sheets

Endpoint adalah URL yang bisa diakses untuk melakukan operasi tertentu. Anatomy of a URL: https://api.example.com/v1/users/42?fields=name,email │ │ │ │ │ │…

Endpoint adalah satu pintu di API: pasangan method dan alamat, misalnya GET /books/1. Alamatnya ditulis sebagai URL. Bayangin alamat kiriman paket. Nama gedungnya (host) membawa paket ke kantor yang benar, nomor raknya (path) menunjuk barang yang mana, dan catatan di labelnya (query string) menyebut pilihanmu, misalnya "yang stoknya ada saja".

🧪 Tebakan cepat: endpoint GET /users/:id menerima request GET /users/1. Nilai req.params.id itu angka 1 atau teks "1"? Tebak dulu, jawabannya ada di bagian "Path parameter: menunjuk satu benda".

Bagian-bagian URL

https://api.tokobuku.test/books/1?fields=title,price

Bagian	Isinya	Dibaca dengan `new URL()`
protocol	`https:`	`url.protocol`
host	`api.tokobuku.test`	`url.host`
path	`/books/1`	`url.pathname`
query string	`?fields=title,price`	`url.search`

Browser sudah punya pembaca URL bawaan, dan hasilnya persis seperti tabel itu:

const url = new URL("https://api.tokobuku.test/books/1?fields=title,price");

console.log(url.pathname);                  // "/books/1"
console.log(url.searchParams.get("fields")); // "title,price"

Host-nya sama untuk semua endpoint di satu API. Yang membedakan endpoint satu dengan yang lain adalah method dan path-nya. Endpoint adalah URL spesifik yang menerima request untuk satu resource.

Endpoint di API Toko Buku

Endpoint	Artinya
`GET /books`	semua buku
`GET /books/{id}`	satu buku
`POST /books`	tambah buku
`GET /authors/{id}/books`	buku-buku milik satu penulis

{id} adalah tempat kosong yang diisi nomor. Dokumentasi biasanya menulisnya {id}, kode Express menulisnya :id. Polanya selalu resource lalu id: siswa nomor 5 ada di /api/siswa/5. Awalan /api sering dipakai kalau API dan website berbagi host yang sama.

Path parameter: menunjuk satu benda

Di /books/1, angka 1 menunjuk buku yang mana. Bagian itu disebut path parameter. Di Express, endpoint-nya ditulis app.get("/books/:id", ...), dan nilainya dibaca dari req.params.id.

Isinya selalu teks: "1", bukan 1. URL itu teks, jadi semua yang dibaca dari URL juga teks. Itu jawaban tebakannya. Akibatnya "1" === 1 bernilai false, jadi ubah dulu jadi angka dengan parseInt(req.params.id) atau Number(req.params.id).

Begini jalannya endpoint latihan, GET /users/:id:

Request	`req.params.id`	`parseInt(...)`	Jawaban
`GET /users/1`	`"1"`	`1`	`200` + `{"id": 1, "name": "Budi"}`
`GET /users/99`	`"99"`	`99`	`404` + `{"error": "User not found"}`

Yang gak ada dijawab 404 Not Found, bukan 200 dengan body kosong.

Query string: pilihan untuk daftar

Query string ada setelah tanda ?, berupa pasangan nama=nilai yang disambung &. Dia gak menunjuk benda, dia mengatur daftar: menyaring, mengurutkan, memotong per halaman.

GET /books?author_id=2
GET /books?author_id=2&sort=price

Spasi gak boleh ada di URL. url.searchParams.set("q", "bumi manusia") menulisnya q=bumi+manusia, encodeURIComponent menulisnya bumi%20manusia. Dua-duanya dibaca balik sebagai spasi.
Filter yang gak ketemu apa-apa tetap dijawab 200 dengan daftar kosong []. Daftarnya ada, isinya saja yang kosong. GET /authors/4/books untuk penulis yang belum punya buku juga 200 dengan [].

Pegangannya: kalau tanpa bagian itu request-nya menunjuk benda lain, taruh di path. Kalau cuma pilihan untuk daftar, taruh di query. Jadi GET /api/getSiswaById?id=5 gak RESTful: satu siswa ditunjuk lewat path, GET /api/siswa/5.

Aturan penamaan

Kata benda jamak. /books, bukan /book atau /getBooks.
Huruf kecil, kata dipisah tanda minus (kebab-case): /best-sellers, bukan /BestSellers atau /best_sellers. Menurut aturan URL, path membedakan huruf besar dan kecil, jadi /Books bisa jadi alamat lain.
Tanpa kata kerja. Method sudah bilang aksinya.
Bersarang secukupnya. /authors/2/books jelas. /authors/2/books/1/reviews/3 kepanjangan.

GET /api/Siswa_Data/getAll melanggar hampir semuanya: huruf besar, garis bawah, dan kata kerja getAll. Versi rapinya GET /api/siswa.

Latihan: satu user lewat path parameter

Bentuknya sama dengan versi Toko Buku ini:

app.get("/books/:id", (req, res) => {
  const id = parseInt(req.params.id);
  if (id === 1) {
    res.json({ id: 1, title: "Laskar Pelangi" });
  } else {
    res.status(404).json({ error: "Book not found" });
  }
});

"/books/:id" menangkap /books/1, /books/99, dan seterusnya.
parseInt(req.params.id) mengubah teks "1" jadi angka 1, supaya id === 1 bisa true.
Cabang else menjawab 404 dengan body error, karena bukunya gak ada.

Di latihan, resource-nya users: user 1 dijawab {"id": 1, "name": "Budi"}, yang lain 404 dengan {"error": "User not found"}.

⚠️ Jebakan yang sering ketemu

Membandingkan teks dengan angka. req.params.id === 1 selalu false, jadi semua user dapat 404. Ubah dulu dengan parseInt.
Satu benda lewat query. /getSiswaById?id=5 bikin URL jadi kata kerja. Tulis /siswa/5.
Gaya penulisan campur aduk. /Siswa_Data/getAll: huruf besar, garis bawah, kata kerja. Pilih huruf kecil dan kata benda jamak, lalu konsisten.
200 untuk yang gak ada. res.json(null) dengan status 200 bikin client mengira datanya ketemu. Pakai 404.

TL;DR: Endpoint = method + path, misalnya GET /books/1; host-nya sama untuk semua endpoint satu API. URL terdiri dari protocol, host, path, dan query string, dan new URL() bisa membacanya. Path parameter (/books/:id) menunjuk satu benda, dan nilainya di req.params.id selalu teks, jadi ubah dengan parseInt sebelum dibandingkan dengan angka. Query string (?author_id=2) mengatur daftar; hasil kosong tetap 200 dengan [], sedangkan benda yang gak ada dijawab 404. Nama path: huruf kecil, kata benda jamak, tanpa kata kerja, misalnya /api/siswa/5.

URL & Endpoint — API