[craftkiller]

My understanding is the big difference is REST must have URLs returned in the API responses to access additional data / actions. So in a REST API you'd have a single URL entrypoint that I'll call "/root". "/root" might then return to you something like:

  {
    "links": {
      "users": "/root/users",
      "posts": "/root/posts",
      "mail": "/root/mail"
    }
  }
  

So then the client could make a request for "/root/users" which would return a list of users along with URLs for how to access individual users.

So then the client could make a request for "/root/users/alice" and the server would return the information on alice along with URLs for actions like sending her a message or deleting her.

But all of that interaction is driven from information returned from the server. All the client needed to begin was just the root URL.

Most non-REST JSON APIs today communicate their endpoints via an out-of-band API documentation like swagger.

Quoting the Fielding:

> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs

> [...]

> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

[jkrejcha]

One of the big things too is the encoding of type information using the mechanisms the standard interfaces provide. In HTTP, this is accomplished using media types (through the Accept and Content-Type headers as well as a few related ones). These media types can be standard but they can be vendored too[1].

With something like

   Content-Type: application/json

   {
       "name": "",
       ...
   }

you don't really know much. With something like example/vnd.mycoolapp.user+json, you get typing information (i.e. you know that the representation of /users/me that the server has given you is a JSON variant of a mycoolapp User. (How the types are known is a priori knowledge of the client (but there are standard link relations you can use to reference API documentation, both human-readable and machine-readable)).

A good example of this is your web browser: it knows how to display text/html documents of various character sets, probably knows text/plain, might know application/json.

The best part is? HTTP has a standard mechanism for defining these link relations even if what you have isn't necessarily amenable to link relations[2] (the Link header). You can use that to navigate through a collection (previous, item, collection, etc), get documentation about the API (service-doc, service-desc), find things that are related (related), get STUN and TURN information (ice-server), etc. I doubt very much of this is used in practice, but there are a very rich set of standardized relationships that could be used here.

(A lot of people admittedly assume "using PUT in a couple of places" is doing REST or that not calling all of your method endpoints doAction.pl or whatever is "RESTful" and I think that definition has become so widespread that talking about something that approaches actually doing something that resembles the architectural style tends to require reduplication.)

[1]: https://www.iana.org/assignments/media-types/media-types.xht...

[2]: https://www.iana.org/assignments/link-relations/link-relatio...

[smj-edison]

This is really quite brilliant! I'm so curious now, do you have examples off the top of your head where you've seen this in practice?

Edit: one other thought, I'm starting to see how the semantic web fits into this vision. Too bad it was too brittle in practice (though the SOLID folks are doing some exciting stuff).

[jkrejcha]

I can't say I've seen that many examples of APIs that use them richly. You see a little bit of in in specs that require something be done a certain way (WHEP in particular requires you send ICE information in ice-server link relations). Part of it probably stems from the fact that a lot of the tooling was built on top of OpenAPI (which had discriminators built in and so people used that for implementing "sum types"), etc, and part of that comes from the fact that a lot of HTTP-based APIs basically only take the content portion of the response, ignoring the headers basically entirely (outside of maybe redirects).

Relatively speaking I think there aren't that many people that know that it is even really a possibility, let alone use it.

(You even see discussions on even whether the status codes are to be used at all, when they were really purpose-built to be generalizable.)

This partially is self-reinforcing: the server libraries don't do anything with media types generally outside of maybe a "FileResponse"-ish class or function and the client libraries don't tend to implement it because it's not supported.

Part of it too may be that interoperability isn't necessarily an underlying goal.

> one other thought, I'm starting to see how the semantic web fits into this vision. Too bad it was too brittle in practice (though the SOLID folks are doing some exciting stuff).

Indeed! There's a lot of similar ideas with this and you definitely have things you can fit in there. :)

[smj-edison]

So I guess then MCP would have some elements of REST, but not all? Poking through their lifecycle page[1], it seems that capabilities (effectively RPCs iiuc) are only negotiated at the beginning, all at once. Whereas it seems that REST is about gradual and dynamic enumeration of available options, by following the next step at each request.

[1] https://modelcontextprotocol.io/specification/2025-06-18/bas...