3 ms·

> 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

> 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.

mumblemumble 6y ago
> 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-wrote/ https://cdsmith.wordpress.com/2011/01/09/an-old-article-i-wr...

mumblemumble 6y ago

> 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-wrote/ https://cdsmith.wordpress.com/2011/01/09/an-old-article-i-wr...