{ "API Status Codes Matter for API Design" }

𝗬𝗼𝘂𝗿 𝗔𝗣𝗜 𝗿𝗲𝘁𝘂𝗿𝗻𝗲𝗱 𝟮𝟬𝟬. 𝗕𝘂𝘁 𝘁𝗵𝗲 𝗿𝗲𝗾𝘂𝗲𝘀𝘁 𝗳𝗮𝗶𝗹𝗲𝗱. 𝗔𝗻𝗱 𝘆𝗼𝘂 𝗰𝗮𝗹𝗹𝗲𝗱 𝘁𝗵𝗮𝘁 𝗮 𝘀𝘂𝗰𝗰𝗲𝘀𝘀. This is one of the most common API mistakes I see. Returning 200 OK for everything then burying the real result in the response body. { "success": false, "message": "User not found" } The client got a 200. But the user wasn’t found. That’s not a success. That’s a lie. 𝗛𝗧𝗧𝗣 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲𝘀 𝗲𝘅𝗶𝘀𝘁 𝗳𝗼𝗿 𝗮 𝗿𝗲𝗮𝘀𝗼𝗻. They’re not decoration. They’re a contract between your API and everyone who consumes it. 𝗧𝗵𝗲 𝗰𝗼𝗱𝗲𝘀 𝘁𝗵𝗮𝘁 𝗮𝗰𝘁𝘂𝗮𝗹𝗹𝘆 𝗺𝗮𝘁𝘁𝗲𝗿: • 200 → Success, here’s your data • 201 → Created successfully • 400 → Bad request, fix your input • 401 → Not authenticated • 403 → Authenticated, but not allowed • 404 → Resource doesn’t exist • 409 → Conflict, something already exists • 422 → Validation failed • 500 → Server broke, not the client’s fault 𝗪𝗵𝗲𝗻 𝘆𝗼𝘂 𝗿𝗲𝘁𝘂𝗿𝗻 𝘁𝗵𝗲 𝘄𝗿𝗼𝗻𝗴 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲: • Frontend devs write broken error handling • Mobile apps show wrong messages to users • Debugging takes twice as long • Your API becomes unpredictable 𝗔 𝗴𝗼𝗼𝗱 𝗔𝗣𝗜 𝘂𝘀𝗲𝘀 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲𝘀 𝗮𝗻𝗱 𝗿𝗲𝘀𝗽𝗼𝗻𝘀𝗲 𝗯𝗼𝗱𝗶𝗲𝘀 𝘁𝗼𝗴𝗲𝘁𝗵𝗲𝗿. The status code tells you what happened. The body tells you why. { "status": 404, "message": "User not found" } { "status": 422, "message": "Phone number is required" } Clear enough to debug. Careful enough not to expose sensitive internals. 𝗗𝗷𝗮𝗻𝗴𝗼 𝗥𝗘𝗦𝗧 𝗙𝗿𝗮𝗺𝗲𝘄𝗼𝗿𝗸 𝗺𝗮𝗸𝗲𝘀 𝘁𝗵𝗶𝘀 𝗲𝗮𝘀𝘆. No excuses. 𝗨𝘀𝗲 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲𝘀 𝗹𝗶𝗸𝗲 𝘆𝗼𝘂 𝗺𝗲𝗮𝗻 𝘁𝗵𝗲𝗺. Your API is a conversation. Make sure it’s saying the right thing. #Django #Python #BackendDevelopment #APIDesign #WebDevelopment #SoftwareEngineering

  • No alternative text description for this image

To view or add a comment, sign in

Explore content categories