Hacker News Reader

> To be fair, many APIs are just that.

My experience is that almost all REST APIs are like that, give or take some documentation. Though I have read about both, I have never worked with a JSON schema or Open API api. I have conservatively worked at least a hundred REST APIs, including both public and private ones.

I’m mildly optimistic about GraphQL, but without a doubt I think one of the best parts is that all GraphQL APIs have typed schemas. There is no discretion on the part of the API provider.

This is similar to a debate regarding programming languages. Some people like more restrictive languages, because they don’t trust others or themselves to reliably use good discretion in the use of powerful features or omission of optional safety checks like types.

> Some people like more restrictive languages, because they don’t trust others or themselves to reliably use good discretion in the use of powerful features

For me, it's not even that. It's that I've discovered that, even when used with discretion, the simple presence of powerful features still makes it harder to reason about how things work. Discretion around powerful features isn't a one-and-done thing; it's an ongoing process of double-checking and verifying for yourself whether that feature is being used properly every time you touch or interact with code that uses it.

A common thread in many seminal papers and essays in the history of programming languages ("Can Programming be Liberated from the Von Neumann Style", "GOTO Statement considered harmful", "Lambda: The Ultimate GOTO", to name a few.) is that, ironically enough, when you take a bird's eye look at things, reducing the power of the tools tends to increase the power of the programmer.

I should say, I'm not meaning that to be a statement in favor of static or dynamic typing; I try to stay out of that debate.[1] To me, the real problem with JSON is that, at least under typical usage, it tends to be weakly typed. (Which is a powerful feature; strong typing is a way of restricting what you can do.) JSON's type system is less expressive than that of basically any well-known programming language, including JavaScript itself, and, out of necessity, people tend to deal with that by overloading its types in ways that may force consumers to use out-of-band knowledge to interpret a message properly. This has a tendency to happen even in the presence of OpenAPI specs or JSON schemata.

[1] Though I'll take this chance to link https://cdsmith.wordpress.com/2011/01/09/an-old-article-i-wr...

Your response is to the typing nature of GraphQL, but this isn't the only strong reason for GraphQL. GraphQL reduces both response payload size to only what is necessary for the client, but also reduces round-trips.

Unless you are writing custom REST endpoints for every aspect of your UI, most formulation of what data a consumer needs will usually resolve in multiple trips to the server. So, you either scale out by having custom REST endpoints to handle each case of this (which both feels odd and presumably won't scale very well), or you take advantage of GraphQL doing this natively.

> Unless you are writing custom REST endpoints for every aspect of your UI

Wouldn't that be the normal way to implement a REST API?

The problem is you might end up writing strange endpoints just to satisfy a specific UI page.

For example, take a small blog, that holds several posts, each with an author.

In GraphQL, you could fetch all the posts, and all info related to the author in the same query (without any new, funny business).

In REST, if you wanted this in a single query, you'd need to define some endpoint like /post-and-authors-list that fetches all the posts and complete author information for each post, whereas most REST implementations would probably involve a small set of CRUD steps on all posts, and then several queries to fetch each author for further information as well (based on the author ID in the post).

So it's not that REST can't implement anything GraphQL wants to implement, but there is a lot more work involved, is harder to scale out with developers, etc.

The paper even says, "the avaliability of a type system —expressed as a schema — is one of the key benefits [of GraphQL]".

In other words, as you say, if there's a schema with the REST API, GraphQL loses one of what the authors claim as a key benefit.

It doesn't lose it - it just doesn't remain an advantage over the alternative.

It's not like if there is a schema with a REST API, the GraphQL alternative becomes un-typed.

What's the difference between "losing it" and "it doesn't remain"? I didn't say GraphQL lost the feature, I said it lost the advantage.

I see also the paper says, in bold, "it is unfair to attribute the gains observed with GraphQL only to the IDE", but elsewhere they trumpet the ability of the IDE to interpret and enforce the schema as significant. And again, we can accept that the feature is useful without conceding that GraphQL has the advantage. We could just as well have an IDE that understands OpenAPI specs an accomplish the same thing.

You said "benefit", not advantage.

I did not, I was paraphrasing the paper.

"By triangulating the results of RQ1 and RQ2, it is clear that the avaliability of a type system — expressed as a schema — is one of the key benefits provided by GraphQL, in terms of reducing the effort to implement queries, when compared to REST."

The paper itself was using the word benefit in comparison to REST.

FWIW, the types possible to express in gql is quite a lot weaker than the ones in openapi, where you can for example say not only is a field a string, but also that it matches a certain format.

You can create custom scalars in GraphQL, which then have shared logic for serialization on the backend and frontend. That knowledge on format does have to be sort of out-of-band but that could probably be added to the standard.

I think REST is definitely playing catch up here though. A standard gql setup generally comes out of the box with type generation, web playgrounds, etc. Of course it's possible now with REST but I really think that gql helped push the state of the art in this space.

huh! Swagger playground is there at least one year before[1] gql was used internally in Facebook and several years before it was available publicly..

[1] https://en.wikipedia.org/wiki/Swagger_(software) [2] https://en.wikipedia.org/wiki/GraphQL

We’ve had these aspects out of the box with oData REST endpoints that have been in production for half a decade.

What do you think may account for the lack of take up iof oData?

I honestly can't say. It's quite easy to use and broadly supported. Even excel can directly pull data from oData Sources with a couple of clicks. If anyone else has some insights into the lack of uptake of oData I would love to hear them though.

I'd say mostly lack of knowledge about it, but sometimes people who are aware it exists don't like the fact that it allows arbitary queries, they think that only implementing specific methods provides more security - which can be achieved by limiting the odata access in any case, so that comes back to lack of knowledge.

Another factor may be that Microsoft used it so some sectors thought it was uncool and spent a long time building other stuff instead ..

We get that out of the box w boring old django/sqlize

we do happen to do more interesting things elsewhere (GPGPU, columnar streaming analytics, reactive frontend, ...), so like sharp edges when a 10X+ lift, but ended up backing up on this layer as it was adding complexity w immature layers vs what felt like similar perceived benefits from reliable boring stuff. it doesn't scratch all our itches, but the big ones are at a layer above/beyond graphql vs rest (eg, auth)

Where do you use the boring pieces in your stack? Mostly around CRUD management of metadata?

basically!