Designing a REST API That Developers Actually Like Using I've consumed hundreds of APIs. The good ones share these patterns. The bad ones... don't. 1. Consistent Response Format // ✅ Good: Always the same shape { "data" : { ... }, "meta" : { "page" : 1 , "per_page" : 20 , "total" : 142 } } // ❌ Bad: Sometimes array, sometimes object, sometimes nested weirdly { "users" : [ ... ] } // List endpoint { "id" : 1 , "name" : "..." } // Get one endpoint { "success" : true , "result" : { ... } } // Different wrapper! Enter fullscreen mode Exit fullscreen mode 2. Proper HTTP Status Codes // Use the RIGHT code, not just 200 and 500 const STATUS = { OK : 200 , CREATED : 201 , NO_CONTENT : 204 , BAD_REQUEST : 400 , UNAUTHORIZED : 401 , FORBIDDEN : 403 , NOT_FOUND : 404 , CONFLICT : 409 , UNPROCESSABLE_ENTITY : 422 , TOO_MANY_REQUESTS : 429 , INTERNAL_ERROR : 500 , }; // Common mistakes: // ❌ 200 with { error: "Not found" } → Use 404 // ❌ 200 with { error: "Unauthorized" } → Use 401/403 // ❌ 500 for validation errors →…