Skip to main content

REST and RESTful

So far in this section we've covered the foundations of API communication. Now let's look at the architectural style that underlies most modern web APIs: REST. Understanding REST helps you design predictable, scalable endpoints—and recognize when "RESTful" claims don't quite match reality.

What's REST (and RESTful)?​

REST (Representational State Transfer) is an architectural style defined by Roy Fielding, focusing on:

  1. Client-server separation
  2. Statelessness
  3. Cacheability
  4. Layered system
  5. Uniform interface (resources, representations)
  6. Code-on-demand (optional)

RESTful APIs strictly follow all these constraints. But here's the thing: most "REST" APIs aren't truly RESTful, and that's okay.

True RESTful APIs require HATEOAS (Hypermedia as the Engine of Application State)—embedding links to related resources in responses:

{
  "id": 1,
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "orders", "href": "/users/1/orders" }
  ]
}

In practice this doesn't happen:

  • Frontend teams rarely use embedded links.
  • Adds complexity without immediate value.

An OpenAPI Specification already gives you 80% of REST's benefits:

  • Resource-centric URLs (/users/{id}).
  • Standard HTTP methods (GET/POST/PUT/DELETE).
  • Clear error handling (4xx/5xx codes).

Unless you're building hypermedia-driven systems, REST is fine. Focus on:

  • Consistent specifications.
  • Predictable error handling.
  • Documentation humans and machines can use.

As your API evolves, you may add RESTful features later if required.

I really recommend High-Performance Programming's video "Rest API - Best Practices - Design".

Tools for REST API Development​

  • Postman: The industry standard with extensive features. However, the forced account creation and cloud-syncing for basic functionality can be frustrating if you just want to quickly test an endpoint. It works well, but the bloat is noticeable.
  • Insomnia: A lighter alternative to Postman. It handles most API testing needs without the extra baggage. Worth trying if you want something simpler.
  • IDE's built-in REST clients: Many modern IDEs (like IntelliJ IDEA, VS Code) have excellent plugins that let you test endpoints directly from your development environment. This keeps you in flow and avoids context switching.
  • Command-line tools like curl, jq, and w3m. They're simple, quick, and the output is just text. It's straightforward to copy-paste commands and their outputs, demonstrating exactly what's happening without relying on screenshots of a GUI tool. This makes documentation more actionable and easier to reproduce.

REST gives you a solid foundation for API design, but don't get caught up in pedantic debates about whether your API is "truly RESTful." Focus on clear specifications, predictable behavior, and documentation that both humans and machines can consume. Pick tools that fit your workflow—whether that's a full-featured GUI client, IDE integration, or command-line utilities—and document your API decisions clearly so the next developer can understand your intent without guessing.