4 ms·

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023, and in 2024 produce an openapi yaml or json file for that API with no other changes, is it somehow no longer a REST api? of course not. The article seems to be predicated on this distinction. > The least-commonly used API model is REST Is that true? I don't think it is frankly, though I suppose if any API that would be a REST api _if it didn't have an openapi spec_ is somehow no longer a REST api, then maybe? But as previously stated, I just don't think that's true. > A signature characteristic of [REST APIs] is that clients do not construct URLs from other information I don't think this is true in practice. Let us consider the case of a webapp that uses a REST api to fetch/mutate data. The client is a browser, and is almost certainly using javascript to make requests. Javascript doesn't just magically know how to access resources, your app code is written to construct urls (example: getting an ID from the url, and then constructing a new url using that extracted ID to make an api call to fetch that resource). In fact, the only situation where I think this description of how a REST api is used is _defensibly_ true (and this is hella weak), is where the REST api in question has provided an openapi spec, and from that spec, you've converted that into a client library (example: https://openapi-ts.dev https://openapi-ts.dev). In such a situation, the client has a nice set of functions to call that abstract away the construction of the URL. But somewhere in the client, _urls are still being constructed_. And going back to my first complaint about this article, this contrived situation combines what the article states are two entirely distinct methods for designing apis (rest vs openapi). Re: the article's description of rpc, I actually don't have any major complaints.

silisili 2y ago
You're being way too polite. The article is garbage and completely incorrect about what REST and OpenAPI even are.
- mvdtnz 2y ago
  You're wrong. The author is using "REST" to mean an API at Level 3 on the Richardson Maturity Model[0] - this was the original conception of what it meant to be a "REST API" before the wider internet decided "REST" meant "nice looking URLs". What he refers to as "OpenAPI APIs" could be called Level 2 Web APIs on the same model. He uses "REST" correctly. He uses "OpenAPI" as a shorthand for the class of web APIs that are resource-based and use HTTP verbs to interact with these resources. [0] https://en.wikipedia.org/wiki/Richardson_Maturity_Model https://en.wikipedia.org/wiki/Richardson_Maturity_Model
  - silisili 2y ago
    I could concede perhaps he wasn't necessarily wrong on REST, though I personally think it's pedantic and incorrect, regardless of what the creator of the term says. Things evolve, and returning a list of objects instead of a list of links was an obvious progression, since spamming 1000s of GET requests doesn't scale well in the post 90s. If the industry at large generally agrees on what makes an API restful, it feels like we should accept such evolution. OpenAPI is a description language and has little to do with an API itself. It's documentation. People were using 'unpure' REST long before it or Swagger even existed. And as the parent pointed out, you can add an openapi spec later, and it doesn't magically change the API itself. Further, it creates a weird circular logic that doesn't work. From https://swagger.io/docs/specification/v3_0/about/ https://swagger.io/docs/specification/v3_0/about/ - "OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs"
turnsout 2y ago
Yeah, the author has an extremely idiosyncratic take on the definition of REST which is either based on a misunderstanding, or a fundamentalist view of "pure" REST.
golly_ned 2y ago
This stood out to me as well. The author must have a particular understanding of REST that differs from the usual sense in which it’s used. He might be technically correct — I haven’t read the primary sources related to REST — but it distracted from the meat and potatoes of the article, which is really a comparison of gRPC and OpenAPI. It seemed very strange for this reason.
- jijji 2y ago
  or he works for Google (author of gRPC) and is being paid to extol the virtues, albeit short sighted, of gRPC
curt15 2y ago
HATEOAS is crucial to what [Roy Fielding](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...) calls REST APIs. >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, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. Most APIs that people call "RESTful" -- regardless of whether they come with an OpenAPI spec -- don't obey HATEOAS. A typical OpenAPI spec describes the possible request paths and verbs. However, you probably wouldn't be able to discover all that information just by starting from the entry point and parsing the `hrefs` in the response bodies.
- robertlagrant 2y ago
  Roy Fielding would also say that you probably don't need that definition of REST. The main advantages most people get from REST are in the standardised tooling, faster browser/library parsing of JSON, HTTP makes firewalls easy, and it looked so much nicer than the incumbent, SOAP[0]. [0] https://www.w3.org/TR/2000/NOTE-SOAP-20000508 https://www.w3.org/TR/2000/NOTE-SOAP-20000508
eadmund 2y ago
> > A signature characteristic of [REST APIs] is that clients do not construct URLs from other information > I don't think this is true in practice. 'recursivedoubts: https://news.ycombinator.com/item?id=42799917 https://news.ycombinator.com/item?id=42799917 The blogger is completely correct. In a true REST (i.e., not JSON-RPC) API, the client has a single entry URL, then calls the appropriate HTTP verb on it, then parses the response, and proceeds to follow URLs; it does not produce its own URLs. Hypertext as the engine of application state. For example, there might be a URL http://foocorp.example/ http://foocorp.example/. My OrderMaker client might GET http://foo.example/ http://foo.example/, Accepting type application/offerings. It gets back a 200 response of type application/offerings listing all the widgets FooCorp offers. The offerings document might include a URL with an order-creation relationship. That URL could be http://foocorp.example/orders http://foocorp.example/orders, or it could be http://foocorp.example/82347327462 http://foocorp.example/82347327462, or it could be https://barcorp.example/cats/dog-attack/boston-dysentery https://barcorp.example/cats/dog-attack/boston-dysentery — it seriously doesn’t matter. My client could POST to that URL and then get back a 401 Unauthorized response with a WWW-Authenticate header with the value ‘SuperAuthMechanism system="baz"’, and then my client could prompt me for the right credentials and retry the POST with an Authorization header with the value ‘SuperAuthMechanism opensesame’ and receive a 201 response with a Location header containing a URL for the new empty order. That could be http://foocorp.example/orders/1234 http://foocorp.example/orders/1234, or it could be https://grabthar.example/hammer https://grabthar.example/hammer — what matters is that my client knows how to interact with it using HTTP verbs, headers and content types, not what the URL’s characters. Then my client might POST a resource with content type application/order-item describing a widget to that order URL, and get back 202 Accepted. Then it might POST another resource describing a gadget, and get back 202 Accepted. Then it might GET the original order URL, and get back a 200 OK of type application/order which shows the order in an unconfirmed state. That resource might include a particular confirm URL to PUT to, or perhaps my client might POST a resource with content type application/order-confirmation — all that would be up to the order protocol definition (along with particulars like 202, or 200, or 201, or whatever). Eventually my client non-idempotently PUTs or POSTs or whatever, and from then on can poll the order URL and see it change as FooCorp fulfills it. That’s a RESTful API. The World Wide Web itself is a RESTful API for dealing with documents and also complete multimedia applications lying about being documents, but the RESTful model can be applied to other things. You can even build a RESTful application using the same backend code in the example, but which talks HTML to human beings whose browsers ask for text/html instead of application/whatever. Or you might build a client which asks for ‘text/html; custom=orderML’ and knows how to parse the expected HTML to extract the right information, and everything shares common backend code. Or you might use htmx and make all this reasonably easy and straightforward. That’s what REST is. What REST is not, is GETting http://api.foocorp.example/v1/order/$ORDERID http://api.foocorp.example/v1/order/$ORDERID and getting back a JSON blob, then parsing out an item ID from the JSON blob, then GETting http://api.foocorp.example/v1/item/$ITEMID http://api.foocorp.example/v1/item/$ITEMID and so forth.

silisili 2y ago

You're being way too polite. The article is garbage and completely incorrect about what REST and OpenAPI even are.

mvdtnz 2y ago
You're wrong. The author is using "REST" to mean an API at Level 3 on the Richardson Maturity Model[0] - this was the original conception of what it meant to be a "REST API" before the wider internet decided "REST" meant "nice looking URLs". What he refers to as "OpenAPI APIs" could be called Level 2 Web APIs on the same model. He uses "REST" correctly. He uses "OpenAPI" as a shorthand for the class of web APIs that are resource-based and use HTTP verbs to interact with these resources. [0] https://en.wikipedia.org/wiki/Richardson_Maturity_Model https://en.wikipedia.org/wiki/Richardson_Maturity_Model
- silisili 2y ago
  I could concede perhaps he wasn't necessarily wrong on REST, though I personally think it's pedantic and incorrect, regardless of what the creator of the term says. Things evolve, and returning a list of objects instead of a list of links was an obvious progression, since spamming 1000s of GET requests doesn't scale well in the post 90s. If the industry at large generally agrees on what makes an API restful, it feels like we should accept such evolution. OpenAPI is a description language and has little to do with an API itself. It's documentation. People were using 'unpure' REST long before it or Swagger even existed. And as the parent pointed out, you can add an openapi spec later, and it doesn't magically change the API itself. Further, it creates a weird circular logic that doesn't work. From https://swagger.io/docs/specification/v3_0/about/ https://swagger.io/docs/specification/v3_0/about/ - "OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs"

turnsout 2y ago

Yeah, the author has an extremely idiosyncratic take on the definition of REST which is either based on a misunderstanding, or a fundamentalist view of "pure" REST.

golly_ned 2y ago

This stood out to me as well. The author must have a particular understanding of REST that differs from the usual sense in which it’s used. He might be technically correct — I haven’t read the primary sources related to REST — but it distracted from the meat and potatoes of the article, which is really a comparison of gRPC and OpenAPI. It seemed very strange for this reason.

jijji 2y ago
or he works for Google (author of gRPC) and is being paid to extol the virtues, albeit short sighted, of gRPC

curt15 2y ago

HATEOAS is crucial to what [Roy Fielding](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...) calls REST APIs. >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, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. Most APIs that people call "RESTful" -- regardless of whether they come with an OpenAPI spec -- don't obey HATEOAS. A typical OpenAPI spec describes the possible request paths and verbs. However, you probably wouldn't be able to discover all that information just by starting from the entry point and parsing the `hrefs` in the response bodies.

robertlagrant 2y ago
Roy Fielding would also say that you probably don't need that definition of REST. The main advantages most people get from REST are in the standardised tooling, faster browser/library parsing of JSON, HTTP makes firewalls easy, and it looked so much nicer than the incumbent, SOAP[0]. [0] https://www.w3.org/TR/2000/NOTE-SOAP-20000508 https://www.w3.org/TR/2000/NOTE-SOAP-20000508

eadmund 2y ago

> > A signature characteristic of [REST APIs] is that clients do not construct URLs from other information > I don't think this is true in practice. 'recursivedoubts: https://news.ycombinator.com/item?id=42799917 https://news.ycombinator.com/item?id=42799917 The blogger is completely correct. In a true REST (i.e., not JSON-RPC) API, the client has a single entry URL, then calls the appropriate HTTP verb on it, then parses the response, and proceeds to follow URLs; it does not produce its own URLs. Hypertext as the engine of application state. For example, there might be a URL http://foocorp.example/ http://foocorp.example/. My OrderMaker client might GET http://foo.example/ http://foo.example/, Accepting type application/offerings. It gets back a 200 response of type application/offerings listing all the widgets FooCorp offers. The offerings document might include a URL with an order-creation relationship. That URL could be http://foocorp.example/orders http://foocorp.example/orders, or it could be http://foocorp.example/82347327462 http://foocorp.example/82347327462, or it could be https://barcorp.example/cats/dog-attack/boston-dysentery https://barcorp.example/cats/dog-attack/boston-dysentery — it seriously doesn’t matter. My client could POST to that URL and then get back a 401 Unauthorized response with a WWW-Authenticate header with the value ‘SuperAuthMechanism system="baz"’, and then my client could prompt me for the right credentials and retry the POST with an Authorization header with the value ‘SuperAuthMechanism opensesame’ and receive a 201 response with a Location header containing a URL for the new empty order. That could be http://foocorp.example/orders/1234 http://foocorp.example/orders/1234, or it could be https://grabthar.example/hammer https://grabthar.example/hammer — what matters is that my client knows how to interact with it using HTTP verbs, headers and content types, not what the URL’s characters. Then my client might POST a resource with content type application/order-item describing a widget to that order URL, and get back 202 Accepted. Then it might POST another resource describing a gadget, and get back 202 Accepted. Then it might GET the original order URL, and get back a 200 OK of type application/order which shows the order in an unconfirmed state. That resource might include a particular confirm URL to PUT to, or perhaps my client might POST a resource with content type application/order-confirmation — all that would be up to the order protocol definition (along with particulars like 202, or 200, or 201, or whatever). Eventually my client non-idempotently PUTs or POSTs or whatever, and from then on can poll the order URL and see it change as FooCorp fulfills it. That’s a RESTful API. The World Wide Web itself is a RESTful API for dealing with documents and also complete multimedia applications lying about being documents, but the RESTful model can be applied to other things. You can even build a RESTful application using the same backend code in the example, but which talks HTML to human beings whose browsers ask for text/html instead of application/whatever. Or you might build a client which asks for ‘text/html; custom=orderML’ and knows how to parse the expected HTML to extract the right information, and everything shares common backend code. Or you might use htmx and make all this reasonably easy and straightforward. That’s what REST is. What REST is not, is GETting http://api.foocorp.example/v1/order/$ORDERID http://api.foocorp.example/v1/order/$ORDERID and getting back a JSON blob, then parsing out an item ID from the JSON blob, then GETting http://api.foocorp.example/v1/item/$ITEMID http://api.foocorp.example/v1/item/$ITEMID and so forth.