4 ms·

> If your API is a REST API, then your clients never have to understand the format of your URLs and those formats are not part of the API specification given to

> If your API is a REST API, then your clients never have to understand the format of your URLs and those formats are not part of the API specification given to clients. Roy Fielding, who coined the term REST: "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-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... I know it's a dead horse, but it's so funny: the "API specification" given to clients, in a truly RESTful system, should only be the initial entry point URI/URL.

resonious 2y ago
Classic case of a good idea going viral, followed by people misunderstanding the idea but continuing to spread it anyway.
eadmund 2y ago
You both agree: when he writes ‘format of your URLs,’ he literally means the format of the URLs, not the format of the resources. Like you, I clicked on the article expecting yet another blogger who doesn’t understand REST but it appears this author has at least some basic knowledge of the concepts. Good for him! I like gRPC too, and honestly for a commercial project it is pretty compelling. But for a personal or idealistic project I think that REST is preferable.
curt15 2y ago
How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models?
- AdieuToLogic 2y ago
  > How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models? HAL[0] is very useful for this requirement IMHO. That in conjunction with defining contracts via RAML[1] I have found to be highly effective. 0 - https://datatracker.ietf.org/doc/html/draft-kelly-json-hal https://datatracker.ietf.org/doc/html/draft-kelly-json-hal 1 - https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/ https://github.com/raml-org/raml-spec/blob/master/versions/r...
- loudgas 2y ago
  Your Web browser is probably the best example. When you visit a Web site, your browser discovers resources and understands how it can interact with them.
  - Thiez 2y ago
    It certainly does not. Sure it can crawl links, but the browser doesn't understand the meaning of the pages, nor can it intelligently fill out forms. It is the user that can hopefully divine how to interact with the pages you serve their browser. Most APIs however are intended to be consumed by another service, not by a human manually interpreting the responses and picking the next action from a set of action links. HATEOS is mostly pointless.
- deathanatos 2y ago
  The responses from prior requests give you URLs which form subsequent requests. For example, if I, GET <account URL> that might return the details of my account, which might include a list of links (URLs) to all subscriptions (or perhaps a URL to the entire collection) in the account. (Obviously you have to get the account URL in this example somewhere too, and usually you just keep tugging on the objects in whatever data model you're working with and there are a few natural, easy top-level URLs that might end up in a directory of sorts, if there's >1.) See ACME for an example; it's one of the few APIs I'd class as actually RESTful. https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1 https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1. Needing a single URL is beautiful, IMO, both configuration-wise and easily lets one put in alternate implementations, mocks, etc., and you're not guessing at URLs which I've had to do a few times with non-RESTful HTTP APIs. (Most recently being Google Cloud's…)
est 2y ago
I think the original REST is only suitable for "file" resources, so there's WebDAV and nobody bothers to use it these days.
jahewson 2y ago
This idea of self-describing REST is now better known as HATEOAS. Personally I think it’s bloated and doesn’t solve a real problem. https://en.m.wikipedia.org/wiki/HATEOAS https://en.m.wikipedia.org/wiki/HATEOAS
- crabmusket 2y ago
  HATEOAS is fantastic when your clients are humans. Not so much when they're code.
  - recursivedoubts 2y ago
    agree entirely: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
- recursivedoubts 2y ago
  HATEOAS is one sub-constraint of the uniform interface constraint of REST, see chapter 2 of my book: https://hypermedia.systems/components-of-a-hypermedia-system/#_hypermedia_as_the_engine_of_application_state_hateoas https://hypermedia.systems/components-of-a-hypermedia-system... It's an important aspect of a truly RESTful network architecture
deathanatos 2y ago
> the "API specification" given to clients, in a truly RESTful system, should only be the initial entry point URI/URL I don't know that I fully agree? The configuration, perhaps, but I think the API specification will be far more than just a URL. It'll need to detail whatever media types the system the API is for uses. (I.e., you'll need to spend a lot of words on the HTTP request/response bodies, essentially.) From your link: > A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state That. I.e., you're not just returning `application/json` to your application, you're returning `<something specific>+json`. (Unless you truly are working with JSON generically, but I don't think most are; the JSON is holding business specific data that the application needs to understand & work with.) That is, "and [the] set of standardized media types that are appropriate for the intended audience" is also crucial. (And I think this point gets lost in the popular discourse: it focuses on that initial entry URL, but the "describe the media types", as Fielding says, should be the bulk of the work — sort of the "rest of the owl" of the spec. There's a lot of work there, and I think sometimes people hearing "all you need is one URL" are right to wonder "but where's the rest of the specification?")
- recursivedoubts 2y ago
  that <something specific> should not be API specific, otherwise you are just smuggling an API specification into a second-order aspect of your system and violating the uniform interface.

resonious 2y ago

Classic case of a good idea going viral, followed by people misunderstanding the idea but continuing to spread it anyway.

eadmund 2y ago

You both agree: when he writes ‘format of your URLs,’ he literally means the format of the URLs, not the format of the resources. Like you, I clicked on the article expecting yet another blogger who doesn’t understand REST but it appears this author has at least some basic knowledge of the concepts. Good for him! I like gRPC too, and honestly for a commercial project it is pretty compelling. But for a personal or idealistic project I think that REST is preferable.

curt15 2y ago

How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models?

AdieuToLogic 2y ago
> How does one even write an API client against a REST API that only publishes the initial entry point? in particular, how should the client discover the resources that can be manipulated by the API or the request/response models? HAL[0] is very useful for this requirement IMHO. That in conjunction with defining contracts via RAML[1] I have found to be highly effective. 0 - https://datatracker.ietf.org/doc/html/draft-kelly-json-hal https://datatracker.ietf.org/doc/html/draft-kelly-json-hal 1 - https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/ https://github.com/raml-org/raml-spec/blob/master/versions/r...
loudgas 2y ago
Your Web browser is probably the best example. When you visit a Web site, your browser discovers resources and understands how it can interact with them.
- Thiez 2y ago
  It certainly does not. Sure it can crawl links, but the browser doesn't understand the meaning of the pages, nor can it intelligently fill out forms. It is the user that can hopefully divine how to interact with the pages you serve their browser. Most APIs however are intended to be consumed by another service, not by a human manually interpreting the responses and picking the next action from a set of action links. HATEOS is mostly pointless.
deathanatos 2y ago
The responses from prior requests give you URLs which form subsequent requests. For example, if I, GET <account URL> that might return the details of my account, which might include a list of links (URLs) to all subscriptions (or perhaps a URL to the entire collection) in the account. (Obviously you have to get the account URL in this example somewhere too, and usually you just keep tugging on the objects in whatever data model you're working with and there are a few natural, easy top-level URLs that might end up in a directory of sorts, if there's >1.) See ACME for an example; it's one of the few APIs I'd class as actually RESTful. https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1 https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1. Needing a single URL is beautiful, IMO, both configuration-wise and easily lets one put in alternate implementations, mocks, etc., and you're not guessing at URLs which I've had to do a few times with non-RESTful HTTP APIs. (Most recently being Google Cloud's…)

est 2y ago

I think the original REST is only suitable for "file" resources, so there's WebDAV and nobody bothers to use it these days.

jahewson 2y ago

This idea of self-describing REST is now better known as HATEOAS. Personally I think it’s bloated and doesn’t solve a real problem. https://en.m.wikipedia.org/wiki/HATEOAS https://en.m.wikipedia.org/wiki/HATEOAS

crabmusket 2y ago
HATEOAS is fantastic when your clients are humans. Not so much when they're code.
- recursivedoubts 2y ago
  agree entirely: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
recursivedoubts 2y ago
HATEOAS is one sub-constraint of the uniform interface constraint of REST, see chapter 2 of my book: https://hypermedia.systems/components-of-a-hypermedia-system/#_hypermedia_as_the_engine_of_application_state_hateoas https://hypermedia.systems/components-of-a-hypermedia-system... It's an important aspect of a truly RESTful network architecture

deathanatos 2y ago

> the "API specification" given to clients, in a truly RESTful system, should only be the initial entry point URI/URL I don't know that I fully agree? The configuration, perhaps, but I think the API specification will be far more than just a URL. It'll need to detail whatever media types the system the API is for uses. (I.e., you'll need to spend a lot of words on the HTTP request/response bodies, essentially.) From your link: > A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state That. I.e., you're not just returning `application/json` to your application, you're returning `<something specific>+json`. (Unless you truly are working with JSON generically, but I don't think most are; the JSON is holding business specific data that the application needs to understand & work with.) That is, "and [the] set of standardized media types that are appropriate for the intended audience" is also crucial. (And I think this point gets lost in the popular discourse: it focuses on that initial entry URL, but the "describe the media types", as Fielding says, should be the bulk of the work — sort of the "rest of the owl" of the spec. There's a lot of work there, and I think sometimes people hearing "all you need is one URL" are right to wonder "but where's the rest of the specification?")

recursivedoubts 2y ago
that <something specific> should not be API specific, otherwise you are just smuggling an API specification into a second-order aspect of your system and violating the uniform interface.