REST API Client with Strong Type Validation

TypeScript types describe what your code expects, but they do not validate external data at runtime. A common mistake is fetching JSON, forcing it into an interface with as, and then passing it directly to UI components. The compiler becomes quiet, but the app can still break if the API returns missing fields, wrong types, or a different structure.

Problematic approach:

          interface User {
            id: number;
            name: string;
            email: string;
            status: "active" | "inactive";
          }

          async function getUsers(): Promise<User[]> {
            const response = await fetch("/api/users");
            const data = await response.json();

            return data as User[];
          }

This does not validate anything. If the API returns { id: "1", fullName: "Anna" }, TypeScript will still believe the result is a valid User.

Better approach with a type guard:

          interface User {
            id: number;
            name: string;
            email: string;
            status: "active" | "inactive";
          }

          function isUser(value: unknown): value is User {
            if (!value || typeof value !== "object") {
              return false;
            }

            const user = value as Record<string, unknown>;

            return (
              typeof user.id === "number" &&
              typeof user.name === "string" &&
              typeof user.email === "string" &&
              (user.status === "active" || user.status === "inactive")
            );
          }

          function parseUsers(value: unknown): User[] {
            if (!Array.isArray(value)) {
              throw new Error("Expected users response to be an array.");
            }

            const validUsers = value.filter(isUser);

            if (validUsers.length !== value.length) {
              throw new Error("Users response contains invalid records.");
            }

            return validUsers;
          }

Safer request function:

          async function getUsers(): Promise<User[]> {
            const response = await fetch("/api/users");

            if (!response.ok) {
              throw new Error("Users could not be loaded.");
            }

            const data: unknown = await response.json();

            return parseUsers(data);
          }

Pay attention to: Treat every API response as unknown until it passes validation. TypeScript protects your code, but validation protects your app from real external data.

Components should not need to understand HTTP details such as status codes, headers, Axios response wrappers, or raw JSON parsing. A frequent mistake is calling fetch or axios inside UI components and letting each component decide how to parse, validate, and handle errors. This creates duplicated request logic and inconsistent behavior across the app.

Problematic approach:

          function UsersPage() {
            const [users, setUsers] = useState<User[]>([]);
            const [error, setError] = useState("");

            async function loadUsers() {
              try {
                const response = await axios.get("/api/users");

                setUsers(response.data);
              } catch {
                setError("Something went wrong.");
              }
            }

            return <UserList users={users} error={error} />;
          }

This makes the component responsible for request execution, response extraction, error handling, and data trust. As the app grows, every page repeats slightly different API rules.

Better API client structure:

          type ApiSuccess<T> = {
            ok: true;
            data: T;
          };

          type ApiFailure = {
            ok: false;
            message: string;
            status?: number;
          };

          type ApiResult<T> = ApiSuccess<T> | ApiFailure;

          async function request<T>(params: {
            url: string;
            validate: (value: unknown) => T;
          }): Promise<ApiResult<T>> {
            try {
              const response = await fetch(params.url);
              const rawData: unknown = await response.json();

              if (!response.ok) {
                return {
                  ok: false,
                  message: "Request failed.",
                  status: response.status
                };
              }

              return {
                ok: true,
                data: params.validate(rawData)
              };
            } catch {
              return {
                ok: false,
                message: "Network or validation error."
              };
            }
          }

Service usage:

          export function getUsers(): Promise<ApiResult<User[]>> {
            return request({
              url: "/api/users",
              validate: parseUsers
            });
          }

Cleaner component:

          async function loadUsers() {
            const result = await getUsers();

            if (!result.ok) {
              setRequestState({
                status: "error",
                message: result.message
              });

              return;
            }

            setRequestState({
              status: "success",
              data: result.data
            });
          }

Pay attention to: Create a service layer that hides HTTP implementation details. Components should receive trusted data or a clear failure result, not raw transport objects.

A reusable API client should not mean “accept any path and return anything.” If every endpoint is typed as string and every response is any, the client becomes a thin wrapper around fetch. It may reduce repeated syntax, but it does not provide strong type validation or reliable developer feedback.

Problematic client:

          async function apiClient(path: string, options?: RequestInit): Promise<any> {
            const response = await fetch(path, options);

            return response.json();
          }

          const user = await apiClient("/users/1");

          console.log(user.fullname.toUpperCase());

TypeScript cannot warn you that the real field might be name instead of fullname, because the response is any.

Better endpoint schema:

          interface Endpoints {
            "/users": {
              get: {
                query: {
                  status?: "active" | "inactive";
                };
                response: User[];
              };
            };

            "/users/:id": {
              get: {
                params: {
                  id: string;
                };
                response: User;
              };
            };
          }

Typed client idea:

          type ApiPath = keyof Endpoints;

          async function get<Path extends ApiPath>(
            path: Path,
            options?: Endpoints[Path] extends { get: infer GetConfig }
              ? GetConfig extends { query?: infer Query }
                ? { query?: Query }
                : never
              : never
          ): Promise<
            Endpoints[Path] extends { get: { response: infer Response } }
              ? Response
              : never
          > {
            const response = await fetch(buildUrl(path, options?.query));
            const data: unknown = await response.json();

            return data as Endpoints[Path]["get"]["response"];
          }

Typed usage:

          const users = await get("/users", {
            query: {
              status: "active"
            }
          });

          users.forEach((user) => {
            console.log(user.name);
          });

Pay attention to: A strong API client should know its allowed endpoints, request parameters, and response models. Avoid generic wrappers that erase the contract you are trying to protect.

API clients are not only about request functions. The UI must also represent request status correctly. Beginners often create separate booleans such as loading, error, empty, and success. These flags can accidentally conflict, producing impossible states like loading and error at the same time.

Problematic state:

          const [loading, setLoading] = useState(false);
          const [error, setError] = useState("");
          const [users, setUsers] = useState<User[]>([]);

          async function loadUsers() {
            setLoading(true);

            try {
              const data = await getUsers();

              setUsers(data);
            } catch {
              setError("Users could not be loaded.");
            }

            setLoading(false);
          }

This does not clearly describe the full request lifecycle. The app can forget to clear an old error, show stale data, or render a blank screen after an empty response.

Better discriminated union:

          type RequestState<T> =
            | { status: "idle" }
            | { status: "loading" }
            | { status: "success"; data: T }
            | { status: "empty" }
            | { status: "error"; message: string };

          const [usersState, setUsersState] = useState<RequestState<User[]>>({
            status: "idle"
          });

          async function loadUsers() {
            setUsersState({ status: "loading" });

            const result = await getUsers();

            if (!result.ok) {
              setUsersState({
                status: "error",
                message: result.message
              });

              return;
            }

            if (!result.data.length) {
              setUsersState({ status: "empty" });
              return;
            }

            setUsersState({
              status: "success",
              data: result.data
            });
          }

Chakra UI rendering:

          if (usersState.status === "loading") {
            return <Skeleton height="120px" />;
          }

          if (usersState.status === "error") {
            return (
              <Alert status="error">
                <AlertIcon />
                {usersState.message}
              </Alert>
            );
          }

          if (usersState.status === "empty") {
            return <Text>No users match the current filters.</Text>;
          }

          if (usersState.status === "success") {
            return <UserTable users={usersState.data} />;
          }

          return <Text>Choose filters and load users.</Text>;

Pay attention to: Use discriminated unions for request states. They make impossible UI states harder to create and make conditional rendering easier to understand.

Not every failed request means the same thing. A network failure, a 401 unauthorized response, a 404 missing resource, a 500 server error, and a validation failure should not produce the same internal state. When all errors become “Something went wrong,” the UI gives poor feedback and debugging becomes difficult.

Problematic error handling:

          async function getUser(id: string): Promise<User> {
            try {
              const response = await fetch(`/api/users/${id}`);

              return response.json();
            } catch {
              throw new Error("Something went wrong.");
            }
          }

This hides the actual reason for failure. The component cannot decide whether to show “log in again,” “record not found,” or “try later.”

Better error model:

          type ApiError =
            | { type: "network"; message: string }
            | { type: "unauthorized"; message: string }
            | { type: "not-found"; message: string }
            | { type: "server"; message: string; status: number }
            | { type: "validation"; message: string };

          type ApiResult<T> =
            | { ok: true; data: T }
            | { ok: false; error: ApiError };

Typed error handling:

          async function requestUser(id: string): Promise<ApiResult<User>> {
            try {
              const response = await fetch(`/api/users/${id}`);

              if (response.status === 401) {
                return {
                  ok: false,
                  error: {
                    type: "unauthorized",
                    message: "Please sign in again."
                  }
                };
              }

              if (response.status === 404) {
                return {
                  ok: false,
                  error: {
                    type: "not-found",
                    message: "User was not found."
                  }
                };
              }

              if (!response.ok) {
                return {
                  ok: false,
                  error: {
                    type: "server",
                    status: response.status,
                    message: "Server error. Try again later."
                  }
                };
              }

              const rawData: unknown = await response.json();

              return {
                ok: true,
                data: parseUser(rawData)
              };
            } catch {
              return {
                ok: false,
                error: {
                  type: "network",
                  message: "Network error. Check your connection."
                }
              };
            }
          }

UI response:

          function getErrorMessage(error: ApiError): string {
            switch (error.type) {
              case "unauthorized":
                return "Your session expired. Please log in again.";

              case "not-found":
                return "This record no longer exists.";

              case "validation":
                return "The API returned data in an unexpected format.";

              case "network":
                return "Connection problem. Please retry.";

              case "server":
                return `Server error (${error.status}). Please try later.`;
            }
          }

Pay attention to: Model API errors as typed categories. This makes debugging easier and allows the UI to give users specific, useful recovery instructions.