Building REST APIs? Don't Make These Mistakes

Before REST, integrating systems often meant CORBA, DCOM, or SOAP — powerful but heavyweight and complex.

Then in 2000, Roy Fielding's PhD dissertation introduced REST: stop exposing remote procedures, start exposing resources.

25+ years later, REST is still everywhere.

Here are the basics many “REST APIs” still get wrong:

𝗨𝗥𝗟𝘀

❌ /getOrder/482

❌ /deleteOrder/482

✅ GET /orders/482

✅ DELETE /orders/482

→ URLs represent resources. HTTP methods represent actions.

𝗦𝗧𝗔𝗧𝗘𝗟𝗘𝗦𝗦𝗡𝗘𝗦𝗦

❌ Server depends on remembering previous requests.

✅ Each request contains the information needed to process it.

→ Makes horizontal scaling much easier.

𝗛𝗧𝗧𝗣 𝗩𝗘𝗥𝗕𝗦

GET → read · POST → create · PUT → replace · PATCH → partial update · DELETE → remove

❌ GET /orders/482/cancel

✅ PATCH /orders/482

{ "status": "cancelled" }

→ GET should never change server state.

𝗦𝗧𝗔𝗧𝗨𝗦 𝗖𝗢𝗗𝗘𝗦

❌ 200 OK for everything.

✅ 201 created · 204 success/no content · 404 not found · 409 conflict · 422 invalid data · 500 server error

→ Status codes are part of your API contract.

𝗩𝗘𝗥𝗦𝗜𝗢𝗡𝗜𝗡𝗚

❌ Breaking clients with silent changes.

✅ /api/v1/orders

→ Keep changes backward-compatible where possible; version breaking changes.

And REST isn't perfect. Over-fetching, under-fetching, and service-to-service performance are some reasons teams also use GraphQL or gRPC.

REST was never simply “JSON + HTTP.”

It's a discipline built around resources, statelessness, uniform interfaces, and predictable communication.

Get those principles right, and your APIs become easier to build, scale, and consume.