API, Autentikasi, dan Keamanan · 1/7

Merancang HTTP API

Resource, method, status code, dan bentuk error yang benar-benar bisa dipakai frontend-mu.

Baca 28 menit

Setelah pelajaran ini kamu bisa

Merancang endpoint di sekitar resource alih-alih aksi
Memilih status code yang tepat tanpa perlu mencari
Mengembalikan error yang benar-benar bisa dipakai frontend
Menjelaskan kenapa idempotency penting untuk retry

API REST menamai benda, dan memakai method HTTP untuk kata kerjanya. Desain pemula yang paling umum menaruh kata kerjanya di URL, yang berarti setiap operasi baru butuh endpoint baru.

Aksi	Kata kerja di URL (hindari)	Berbasis resource (utamakan)
Daftar venue	`GET /getVenues`	`GET /venues`
Satu venue	`GET /getVenue?id=42`	`GET /venues/42`
Membuat	`POST /createVenue`	`POST /venues`
Mengubah	`POST /updateVenue`	`PATCH /venues/42`
Menghapus	`POST /deleteVenue`	`DELETE /venues/42`
Booking-nya	`GET /getVenueBookings?id=42`	`GET /venues/42/bookings`

Status code

Kamu sudah menemuinya di modul 1. Ini keputusannya, sebagai urutan pertanyaan yang perlu ditanyakan.

Coba sendiri

Keputusannya sebagai sebuah function. Ini urutan berpikirnya, dan ia menghilangkan tebak-tebakan.

function statusFor(situation) {
  // Ask in this order. The first yes wins.
  if (!situation.knownMethod)      return [405, "Method Not Allowed"];
  if (!situation.parsable)         return [400, "Bad Request"];
  if (!situation.authenticated)    return [401, "Unauthorized"];
  if (!situation.permitted)        return [403, "Forbidden"];
  if (!situation.exists)           return [404, "Not Found"];
  if (!situation.valid)            return [422, "Unprocessable Content"];
  if (situation.conflict)          return [409, "Conflict"];
  if (situation.rateLimited)       return [429, "Too Many Requests"];
  if (situation.created)           return [201, "Created"];
  if (situation.noBody)            return [204, "No Content"];
  return [200, "OK"];
}

const base = {
  knownMethod: true, parsable: true, authenticated: true,
  permitted: true, exists: true, valid: true,
};

const cases = [
  ["read a venue that exists", { ...base }],
  ["created a venue", { ...base, created: true }],
  ["deleted a venue", { ...base, noBody: true }],
  ["malformed JSON body", { ...base, parsable: false }],
  ["no session cookie", { ...base, authenticated: false }],
  ["signed in, not the owner", { ...base, permitted: false }],
  ["venue id does not exist", { ...base, exists: false }],
  ["nights = -5", { ...base, valid: false }],
  ["name already taken", { ...base, conflict: true }],
  ["too many attempts", { ...base, rateLimited: true }],
  ["PATCH not supported here", { ...base, knownMethod: false }],
];

for (const [label, situation] of cases) {
  const [code, text] = statusFor(situation);
  console.log(String(code) + " " + text.padEnd(22) + label);
}

console.log("");
console.log("Note 401 comes before 403, and 403 before 404. Order matters:");
console.log("checking existence before permission leaks whether a record exists.");

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Body error yang bisa dipakai frontend

json

// ❌ Useless: which field? what do I show the user?
{ "error": "Validation failed" }

// ❌ Dangerous: leaks your schema and file paths to an attacker.
{ "error": "SQLITE_CONSTRAINT: UNIQUE constraint failed: users.name_key at /app/features/auth/users.ts:73" }

// ✅ Machine-readable code, plus per-field messages.
{
  "error": "validation_failed",
  "fields": {
    "nights": "Must be between 1 and 30",
    "email": "That does not look like an email address"
  }
}

Peta fields adalah bentuk dari pelajaran form — ia memungkinkan client menampilkan setiap pesan di sebelah input-nya sendiri. Kode error yang stabil memungkinkan client bercabang tanpa mencocokkan teks.

Idempotency

Kamu sudah menemui istilahnya di modul 1: melakukannya dua kali menghasilkan kondisi yang sama seperti sekali. Ini penting karena jaringan melakukan retry. Client mobile di kereta mengirim sebuah request, response-nya hilang, lalu ia mengirim lagi — server sekarang menerimanya dua kali.

Coba sendiri

Retry yang sama terhadap tiga desain. Hanya satu yang selamat.

let bookings = [];
let charges = [];

// POST /bookings - not idempotent. A retry creates a second booking.
function postBooking(payload) {
  bookings.push({ id: bookings.length + 1, guest: payload.guest });
  charges.push(payload.amount);
  return bookings.length;
}

// PUT /bookings/:id - idempotent. A retry overwrites the same row.
function putBooking(id, payload) {
  const existing = bookings.find((b) => b.id === id);
  if (existing) existing.guest = payload.guest;
  else bookings.push({ id: id, guest: payload.guest });
  return id;
}

// POST with an idempotency key - safe retries for a create.
const seenKeys = new Map();
function postBookingWithKey(key, payload) {
  if (seenKeys.has(key)) return seenKeys.get(key);      // replay the first result
  const id = bookings.length + 1;
  bookings.push({ id: id, guest: payload.guest });
  charges.push(payload.amount);
  seenKeys.set(key, id);
  return id;
}

console.log("--- POST twice (a lost response, then a retry) ---");
postBooking({ guest: "Ana", amount: 850000 });
postBooking({ guest: "Ana", amount: 850000 });
console.log("bookings:", bookings.length, " charges:", charges);
console.log("   The customer was charged twice.");

bookings = []; charges = [];
console.log("");
console.log("--- PUT twice ---");
putBooking(1, { guest: "Ana" });
putBooking(1, { guest: "Ana" });
console.log("bookings:", bookings.length);

bookings = []; charges = []; seenKeys.clear();
console.log("");
console.log("--- POST twice with the same idempotency key ---");
postBookingWithKey("req-abc-123", { guest: "Ana", amount: 850000 });
postBookingWithKey("req-abc-123", { guest: "Ana", amount: 850000 });
console.log("bookings:", bookings.length, " charges:", charges);
console.log("   One booking, one charge. The retry replayed the first answer.");

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Tugas praktik

Rancang endpoint untuk fitur progres di proyek ini: membaca progres milikmu sendiri, menandai sebuah pelajaran selesai, dan membatalkan tandanya. Tulis method, path, status code, dan body error untuk masing-masingnya. Lalu bandingkan desainmu dengan features/progress/actions.ts dan catat apa yang tidak lagi dibutuhkan karena memakai Server Action.

Hasil yang diharapkan

Sebuah URL, satu method per operasi — dan tidak perlu semua itu saat pemanggilnya adalah UI-mu sendiri.