Designing the Perfect REST API

Despite the rise of GraphQL and gRPC, REST remains the undisputed standard for web APIs. But designing a good REST API is more than just returning JSON. It requires strict adherence to conventions and a focus on Developer Experience (DX).

Nouns, Not Verbs

A common mistake is using verbs in endpoint URLs. REST URLs should represent resources (nouns), and HTTP methods should represent the actions.

• ❌ POST /getUsers
• ❌ POST /updateArticle/12
• ✅ GET /users
• ✅ PUT /articles/12

Proper HTTP Status Codes

Don't be the developer who returns a 200 OK response with an error payload inside the JSON body. Utilize the full spectrum of HTTP status codes:

// A proper 404 Not Found error response
{
  "success": false,
  "error": {
    "code": "ARTICLE_NOT_FOUND",
    "message": "The article with ID 12 does not exist."
  }
}

Use 201 Created when a resource is successfully made. Use 401 Unauthorized for missing authentication, and 403 Forbidden when the user lacks permissions. Consistency in these codes allows SDKs and frontend clients to handle errors gracefully without parsing arbitrary string messages.