API Design Review: Authentication, Validation, RESTful APIs, and GraphQL

API design is not only about returning data. It also includes authentication, validation, error handling, status codes, and interface style.

Common Authentication Methods

Basic Authentication uses username and password. It is simple, but must be protected by HTTPS.

Token-Based Authentication often uses JWT.

Authorization: Bearer <token>

OAuth 2.0 is common for third-party login, such as Google or GitHub sign-in.

API Keys are often used for service-to-service calls.

Validation

API inputs must be validated. In the TypeScript ecosystem, Zod is a common choice.

const UserSchema = z.object({
  name: z.string(),
  age: z.number().min(0),
});

Validation prevents bad data from entering business logic.

RESTful APIs

REST is centered on resources.

GET /api/users
GET /api/users/1
POST /api/users
PUT /api/users/1
DELETE /api/users/1

Common status codes:

200: success
201: created
400: invalid request
401: unauthenticated
403: forbidden
404: not found
500: server error

GraphQL

GraphQL lets clients declare exactly what data they need.

Core concepts:

Schema: type definition
Query: read operation
Mutation: write operation
Subscription: real-time updates
Resolver: field resolution function

query {
  user(id: "1") {
    id
    name
  }
}

REST is simpler and direct. GraphQL is flexible but adds complexity. Choose based on team and product needs.

Deeper Notes

When reviewing this topic, do not memorize names only. Focus on authentication, authorization, validation, REST resource modeling, GraphQL boundaries, and error semantics. If this stays at the definition level, it becomes hard to explain in interviews or apply in projects. A stronger way to study it is to place it in a concrete scenario: who calls it, where the input comes from, what happens on failure, and whether data or state can be processed twice.

Backend design is not just making endpoints work; authentication, validation, errors, idempotency, logs, and versioning need clear places.
API fields should express business meaning instead of directly exposing table structure.
When reviewing an API, check success, authorization failure, invalid input, missing resources, and dependency failure.

In a real project, use it as a decision framework: identify inputs, constraints, failure modes, and observability before choosing a specific tool or pattern. If a solution looks simple, keep asking whether it still works when scale grows, permissions change, recovery matters, and more people collaborate on it.

Practical Checklist

Identify where this concept sits in the system: development-time constraint, runtime behavior, infrastructure capability, or collaboration workflow.
Write one minimal working example and one failure example; only knowing the happy path is usually not enough.
Record common misuses: edge cases, permission assumptions, performance assumptions, sync/async differences, or environment differences.
Connect the concept to a project experience so that an interview answer can be grounded in real tradeoffs.
End with one sentence about tradeoff: what it gives up and what it buys.

Self-Check Questions

What core problem does this topic solve?
What alternatives exist, and what are their costs?
Where are the most likely edge cases?
How would code, tests, or monitoring prove that it is reliable?

Applied Scenario

A concrete way to study this topic is a user or content management system. The frontend submits a form; the backend authenticates the caller, checks permission, validates input, runs business logic, and returns stable status codes and error shapes. A mature backend endpoint must cover token expiration, missing permission, duplicate submission, invalid input, database failure, and dependency timeout. Documentation, logs, monitoring, and tests should all be built around these paths.

Common Pitfalls:

Mixing up authentication and authorization.
Only validating on the frontend and trusting incoming requests.
Returning 500 for every error, making recovery impossible for callers.

Table of Contents