RESTful API Design

Definition

The art of structuring API endpoints, status codes, and JSON response bodies so that they are highly predictable, logical, and easy for other developers to consume.

Explain Like I'm New

If you build an API that returns a `200 OK` status code when a user fails to login, but the JSON says `{ "error": true }`, you have built a terrible API. Good RESTful design means using HTTP features exactly as they were intended to be used.

Real World Example

Stripe's API is considered the gold standard of RESTful design. It uses strict nouns, predictable nested relationships, standard HTTP error codes, and consistent JSON object wrappers.

Common Use Cases

•System Architecture
•Developer Experience (DX)

Interactive Example

Console output will appear here...

Interview Questions

basic

Should API URLs use uppercase letters, snake_case, or kebab-case?

intermediate

If a client successfully `POST`s a new user to the database, what should the API return in the response body?

Flash Cards

Question

Which casing?

Click to reveal answer

Answer

kebab-case (lowercase words separated by hyphens). E.g., `/api/user-profiles`.

Question

What to return on POST?

Click to reveal answer

Answer

It should return a `201 Created` status code, and the body should contain the newly created object (including its new database-generated ID), so the client doesn't have to make a second GET request to fetch the ID.