Forms: From Input to API Payload

The plain-language idea

Forms get a lot of attention as a UI and accessibility problem — labels, focus order, error messaging. This lesson stays on the narrower, data-layer slice: what happens to the data itself between a user typing into fields and the server receiving a request it can actually use. Four concerns live here:

• Client-side validation is a UX optimization, not a security boundary. Checking that a field is filled in or shaped correctly before submitting gives the user instant feedback without a round trip. It does not protect the server. Anyone can bypass a browser entirely and send whatever request body they want directly to the API, so the validation that actually matters for correctness and security has to run again, independently, on the server. Client-side validation improves the experience; it does not enforce anything.
• Form state and API payload shape are usually different shapes, and turning one into the other is real code, not something that happens for free. A form might track a date as three separate fields because that's convenient to render as three inputs, while the API expects one ISO date string. Someone has to write the function that combines them.
• Submission state has to be tracked and acted on, specifically to disable the submit control and show a pending indicator while the request is in flight — otherwise an impatient double-click fires the same request twice.
• A validation error response has to be routed back to the specific field it's about, not flattened into one generic failure message for the whole form.

See it in a real thing: submitting a signup form

type FormState = {
  email: string;
  birthDay: string;
  birthMonth: string;
  birthYear: string;
};

type ApiPayload = {
  email: string;
  birthDate: string; // ISO format, e.g. "1994-03-21"
};

// The transform step: form-convenient shape -> API-expected shape.
function toPayload(form: FormState): ApiPayload {
  const month = form.birthMonth.padStart(2, "0");
  const day = form.birthDay.padStart(2, "0");
  return {
    email: form.email.trim(),
    birthDate: `${form.birthYear}-${month}-${day}`,
  };
}

function useSignupForm() {
  const [form, setForm] = useState<FormState>({ email: "", birthDay: "", birthMonth: "", birthYear: "" });
  const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
  const [submitting, setSubmitting] = useState(false);

  async function handleSubmit() {
    if (submitting) return; // guards against a double-click firing this twice
    setSubmitting(true);
    setFieldErrors({});

    try {
      const res = await fetch("/api/signup", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(toPayload(form)),
      });

      if (!res.ok) {
        // The server's validation is the one that actually counts. Its response
        // shape is keyed by field name, so route each message back to that field.
        const body = await res.json(); // e.g. { errors: { email: "already in use" } }
        setFieldErrors(body.errors ?? {});
        return;
      }

      // handle success
    } finally {
      setSubmitting(false);
    }
  }

  return { form, setForm, fieldErrors, submitting, handleSubmit };
}

fieldErrors.email can now be read directly by the email input's own error text, rather than a single banner saying something failed somewhere. The submitting flag both disables the submit control and prevents handleSubmit from re-entering while a request is already in flight.

What people usually miss

Watch out

• Client-side validation can always be bypassed. It's there for a fast, friendly experience, not as the thing that actually keeps bad or malicious data out — the server has to re-validate everything, independent of what the client already checked.
• The transform from form state to payload is not automatic. A form field named the same thing as an API field is a coincidence, not a guarantee — the moment the shapes diverge (split fields, different casing, computed values) something has to explicitly bridge them.
• Disabling the button visually isn't the same as guarding the handler. A UI-only disabled state can still let a second submission slip through if the click and the re-render race each other; the code-level guard is what actually prevents it.
• A single "something went wrong" message throws away information the server already gave you. If the response says which field failed and why, that detail belongs on that field, not discarded in favor of one generic banner.
• A successful submission with a payload the server silently coerced isn't actually success. If the API accepts a wrong shape by guessing intent, bugs surface later somewhere else in the system, much harder to trace back to this form.

Why this matters in interviews

"Walk me through what happens from clicking submit to the server responding" is a common way to probe whether a candidate has actually built a real form or only styled one — the transform step and the double-submission guard are the two details that separate the two.