3 ms·

TLDR?

by pwpwp 8y ago

TLDR?

kierenj 8y ago
I'm 11 sections in and haven't found an example other than a worryingly-complex media type specification..
jtms 8y ago
Yeah seriously... +1 to this. Even just a handful of examples of client and server usage would be far more useful for determining if it’s worth digging deeper
- porphyrogene 8y ago
  This is a formal proposition. If it catches on I expect others to explain it in various levels of complexity but this document is intended to be dense and deeply descriptive.
  - deleted 8y ago
    [deleted]
  - GordonS 8y ago
    Sure, but couldn't it begin with an executive summary? If you take RFCs as an example, many start with a simplified description or problem statement before then proceeding to get into the details.
geezerjay 8y ago
> TLDR? Some guy tries to make a case regarding web API design by being both overly pedantic and opinionated on what REST is and how everyone is doing it wrond, proceeds to assert that REST done according to the author's opinion is also wrong, and from that point on (which drags through a dozen sections to make) the author presents "a manifesto" which is the author's opinion on how web APIs should be designed and produces a convoluted definition of a strategy that solves nothing but increases complexity. Some assertions are bafling at best, such as claiming that JSON is somehow not a media type but a message type, which is just wrong. The silliness continues in other baseless assertions such as asserting that developers are not aware that document types such as JSON are used to define JSON-based document formats, or that "Creating a new Media Type for our API is generally considered bad practice", which is just plain wrong, or for some reason conflating the thery part of a URL with the media type which is an assertion that raises some questions.
oscargrouch 8y ago
For me, its basically to add support for metadata in REST, by using things like JSON-LD to describe the layout of data and be competitive with what GraphQL is offering. Of course there are a common definition for data and metadata, trying to define a common standard. It's funny how in the end this will end into reinvent a thing like protobuf, but in JSON, much more verbose, and that can't be read by a human anyway. GraphQL at least do all this while being human-friendly and allowing to define whats needed 'by hand' or by a machine. (But i also dont think this is a great thing to use if the communication is internal and M2M anyway, but its a great solution to serve some api to a bigger crowd of heterogeneous clients)
SolarNet 8y ago
TL;DR: An argument for (with an included example spec) a protocol that solves many of the problems that graphql solves but at the REST layer (e.g. rather than ontop of the REST layer). (As a personal aside: The difference between this spec and GraphQL is relatively minor, they seem equally complex in implementation details (e.g. correctly implementing a graphql server/resolvers is no cakewalk; and correctly implementing either in a less-programming-time way would require a large amount of meta-programming; something that this spec doesn't necessarily solve, or even seem to hint at, yet uses as an argument for it), the only real improvement is that this one is a layer lower (theoretically one less layer of abstraction/indirection improves performance and simplicity) and is not owned by Facebook).

TLDR?

by pwpwp 8y ago

TLDR?

kierenj 8y ago

I'm 11 sections in and haven't found an example other than a worryingly-complex media type specification..

jtms 8y ago

Yeah seriously... +1 to this. Even just a handful of examples of client and server usage would be far more useful for determining if it’s worth digging deeper

porphyrogene 8y ago
This is a formal proposition. If it catches on I expect others to explain it in various levels of complexity but this document is intended to be dense and deeply descriptive.
- deleted 8y ago
  [deleted]
- GordonS 8y ago
  Sure, but couldn't it begin with an executive summary? If you take RFCs as an example, many start with a simplified description or problem statement before then proceeding to get into the details.

geezerjay 8y ago

> TLDR? Some guy tries to make a case regarding web API design by being both overly pedantic and opinionated on what REST is and how everyone is doing it wrond, proceeds to assert that REST done according to the author's opinion is also wrong, and from that point on (which drags through a dozen sections to make) the author presents "a manifesto" which is the author's opinion on how web APIs should be designed and produces a convoluted definition of a strategy that solves nothing but increases complexity. Some assertions are bafling at best, such as claiming that JSON is somehow not a media type but a message type, which is just wrong. The silliness continues in other baseless assertions such as asserting that developers are not aware that document types such as JSON are used to define JSON-based document formats, or that "Creating a new Media Type for our API is generally considered bad practice", which is just plain wrong, or for some reason conflating the thery part of a URL with the media type which is an assertion that raises some questions.

oscargrouch 8y ago

For me, its basically to add support for metadata in REST, by using things like JSON-LD to describe the layout of data and be competitive with what GraphQL is offering. Of course there are a common definition for data and metadata, trying to define a common standard. It's funny how in the end this will end into reinvent a thing like protobuf, but in JSON, much more verbose, and that can't be read by a human anyway. GraphQL at least do all this while being human-friendly and allowing to define whats needed 'by hand' or by a machine. (But i also dont think this is a great thing to use if the communication is internal and M2M anyway, but its a great solution to serve some api to a bigger crowd of heterogeneous clients)

SolarNet 8y ago

TL;DR: An argument for (with an included example spec) a protocol that solves many of the problems that graphql solves but at the REST layer (e.g. rather than ontop of the REST layer). (As a personal aside: The difference between this spec and GraphQL is relatively minor, they seem equally complex in implementation details (e.g. correctly implementing a graphql server/resolvers is no cakewalk; and correctly implementing either in a less-programming-time way would require a large amount of meta-programming; something that this spec doesn't necessarily solve, or even seem to hint at, yet uses as an argument for it), the only real improvement is that this one is a layer lower (theoretically one less layer of abstraction/indirection improves performance and simplicity) and is not owned by Facebook).