Replies: 5 comments 19 replies
-
|
I like the suggestion of SDL being published to a well known endpoint, similar to OIDC jwks. It's extremely common for context to be compiled away from SDL to the deployed schema where developer intention is lost. Custom directives are a great example of this where they may not be stored with your API metadata. |
Beta Was this translation helpful? Give feedback.
-
|
(You may be interested in this comment: #1019 (reply in thread)) |
Beta Was this translation helpful? Give feedback.
-
|
Agreed on the confusion! As a tooling maintainer it’s very unclear. Stating that introspection & SDL should be equivalent is something I can agree on. It’s very important that each spec feature be reflected in both places as the language evolves, so it’s a good idea to make IDL parity explicit. One thing to note as well - graphql services are not necessarily for server only - as a service description language, you can use it to describe a graphql schema that, for example, is executed entirely in the browser main process, or on a device client (this is how MS Teams 1 worked!). All the more reason why an SDL file may be even more practical than shipping a JSON introspection file. Many services may not want to publish an SDL file to a public and/or well known endpoint as it may be a security concern. I would not reccomend making schema introspection or SDL available in production for most commercial, multitenant platforms. That said, a well known schema endpoint would be nice for those who publish introspection, such as platforms with customer facing APIS, or for internal developer tooling, and has been recommended before. For example, graphql playground, if your initial schema URL returns a failure response, tries /graphql before giving up. I have seen |
Beta Was this translation helpful? Give feedback.
-
|
The main reason that the SDL is not used as the primary interchange format for introspection information is that it is not forwards compatible. If the server adds support for a new feature of GraphQL (let's say unions implementing interfaces, e.g. That said, I am definitely not arguing for "introspection JSON" to be the interchange format. There is no singular introspection query, so introspection JSON only has meaning when combined with an implied or explicit introspection document - and it's rare to see it bundled with an explicit one! |
Beta Was this translation helpful? Give feedback.
-
|
@benjie ,
that's a strange understanding of 'forward compatibility'. Usually it is: 'Any valid document for version 1 is valid for version 2'.
you actually say "if Server App moves to support next version of GraphQL Spec, AND adds features using this later version" then old client breaks. That's not about SDL. It is about server app dev changing the server app. Adding new stuff, types, fields, whatever and possibly breaking OLD unchanged clients. That can happen and maybe happening already today, and nothing to do with SDL |
Beta Was this translation helpful? Give feedback.
-
|
Imagine GraphiQL used SDL. You run a GraphiQL version that is compliant with the June2018 release of GraphQL. A user opens GraphiQL, GraphiQL fetches the SDL, parses it, and then makes operations available to the user. Now server updates to June 2023 release of GraphQL, and adds features to the server such as "unions implementing interfaces". The SDL now contains A user opens GraphiQL, GraphiQL fetches the SDL, attempts to parse it, FAILS because it does not understand this new syntax, and now there are no operations available to the user, even though it was working just yesterday. The fictional GraphiQL in this scenario is not forwards compatible with GraphQL because it uses the SDL, and changes to SDL break parsing. Now imagine todays GraphiQL which uses introspection. You run a GraphiQL version that is compliant with the June2018 release of GraphQL. A user opens GraphiQL, GraphiQL issues its introspection query against the GraphQL API, and then makes operations available to the user. Now server updates to June 2023 release of GraphQL, and adds features to the server such as "unions implementing interfaces". The SDL now contains A user opens GraphiQL, GraphiQL issues its introspection query against the GraphQL API, and then makes operations available to the user. The user can still issue the exact same operations they were executing yesterday. The real GraphiQL in this scenario is forwards compatible with GraphQL because it uses introspection, and changes to introspection in GraphQL are backwards compatible thanks to the fundamental backwards compatible guarantees that the GraphQL specification makes with regard to field selection versus new fields. Sure, GraphiQL can't understand what the new features are (it doesn't even know they exist!) but it's still compatible for all its previously valid operations. This is critical.
That's exactly what I'm saying. With introspection, any introspection query for version 1 is valid for version 2, and will not cause the client to baulk.
You are wrong, GraphQL enables us to add features to GraphQL itself and to server APIs without breaking old clients. That's one of the fundamental properties of GraphQL that makes it great! Lee frequently comments how Facebook have not made breaking changes to their GraphQL APIs for best part of a decade and that's despite adding new functionality and updating their GraphQL version. This would not be possible if clients were to use SDL as the introspection format rather than issuing their own introspection queries. It has everything to do with why SDL is not used for this. |
Beta Was this translation helpful? Give feedback.
-
did I suggest tools switch to SDL?! Again: "SDL for humans, Intro for tools". GraphiQL will continue to work with Intro and nothing will break. SDL, delivered as text from a dedicated endpoint, might change over time - signaling to human that there's new stuff there. Your entire example is flawed.
absolutely agree that this is great! The only problem is that your example of 'breakage' (adding union with interfaces) - does not fall under the intended scenario of 'forward compatibility'. Let's look at a hypothetical scenario, with ALL involved actors.
Your argument does not work. All this stuff has nothing to do with SDL vs Intro, which is a subject here. Forward compatibility has nothing to do with this. |
Beta Was this translation helpful? Give feedback.
-
|
It is currently the case that given a spec-compliant GraphQL API, it is possible to generate SDL from the results of introspection that fully represents the GraphQL API, such that you can build a new GraphQL API from only this SDL which would produce the same introspection results. This is a very useful property for tooling because it means that using the SDL generated in this way is equivalent to issuing their own introspection query. However, introspection is still the primary method you should use to see which features of a GraphQL API you can use for various reasons that we've discussed in other threads. The confusion comes when you think of directives applied to the schema as something intrinsic to the schema, simply because they're expressed in SDL. They are not something intrinsic; they're directives - commands - that tell the server to do something special when it's building the schema from SDL. For example, you might have a type Person { ... }
type Query {
allPeople: [Person] @connection
}would become: type Person { ... }
type Query {
allPeople: PersonConnection
}
type PersonConnection {
edges: [PersonEdge]
pageInfo: PageInfo
}
type PersonEdge {
node: Person
cursor: String
}Note how the directive This is what schema directives are in GraphQL today. If you use the reference implementation of GraphQL then (AST nodes aside) there is no runtime details of the directives that were applied - they literally do not exist at runtime, and thus they are not represented in introspection (hard to represent something that does not exist...) and the SDL generated from that introspection does not reflect these directives, again, because they do not exist at runtime. |
Beta Was this translation helpful? Give feedback.
-
|
Right; I wasn't intending to write an actual spec in my comment so I clearly wasn't sufficiently precise with my language. Try this replacement paragraph:
As I've said many times, introspection is the source of truth. |
Beta Was this translation helpful? Give feedback.
-
|
@acao , thanks for your feedback!
well, this is in fact an inti-pattern 'security by obscurity'. You feel you add security if you do not publish any meta-info about your API, like do not enable introspection. Like they cannot abuse/attack endpoints (fields/queries) if they (bad) guys do not know about them, only my clients would know. Believe me, bad guys will know, it's a minor bump on their quest, while it is a huge pain for your legit customers. Security by obscurity is not a good security. |
Beta Was this translation helpful? Give feedback.
-
|
@rivantsov i think you are replying in the wrong place here. At IBM and other companies we exposed our graphiql schema and introspection to our customers, so what? What I’m saying is that exposing your introspection capability over a public, non-authorized network can open you up to abuse if you don’t have proper controls in place. Also, you need to engage the WG with some more respect. Some of the ways you are interacting here with people trying to help you are downright rude and condescending. This is not reddit, this is a community governed working group. |
Beta Was this translation helpful? Give feedback.
-
|
sorry if I offended anyone. But in this particular response I have a hard time finding anything offending. Referencing 'security by obscurity' is rude?! |
Beta Was this translation helpful? Give feedback.
-
|
'Security through obscurity' - it is not a derogatory label, it is a legit tech concept: https://en.wikipedia.org/wiki/Security_through_obscurity (ok it is THROUGH, not BY - my bad).
|
Beta Was this translation helpful? Give feedback.
-
|
GraphQL has one language; for example the following is a valid GraphQL document: type Query {
a: Int
}
query Q {
a
}Note how this is a mixture of schema definition and operation definition using the same language. |
Beta Was this translation helpful? Give feedback.
-
|
Primarily I see them used when discussing a GraphQL scenario - e.g. you want to indicate a query but you need to talk about the schema that goes with it too. i.e. I see them used by humans, but I can't think of an example of them being used by machines. The spec has this to say:
|
Beta Was this translation helpful? Give feedback.
-
|
that's one of the 'strangest' parts of the spec, that you may (spec allows this if server does not mind) send type def to server, but does NOT even say ANY possible purpose of this action! Schema and type defs is the product of the server, and why client would send some type def - absolutely confusing. |
Beta Was this translation helpful? Give feedback.
-
|
Parts of English are only useful when talking with mathematicians. Parts of English are only useful when talking with technologists. These parts of English are not "different languages" purely because they're not useful in all possible circumstances. RFC2119 defines very strict rules around how certain key words can be used in an RFC, but this does not define a new language, nor does it change the meaning of these terms when used in the general English language. GraphQL defines a formal language via a formal grammar and the vast majority of it is used for both defining the schema and for defining an operation. It is one language with two primary use cases. Other use cases are left open to innovation; what value would there be in forbidding these things from occurring in the same document? Here's a use case off the top of my head: query MyQ {
jsonField @castJSON(as: "MyJSONType") {
myKey
}
}
type MyJSONType {
myKey: String!
myOtherKey: [Int]
}A client could take a document such as this one, split it into a pure GraphQL query (e.g. |
Beta Was this translation helpful? Give feedback.
-
|
@benjie |
Beta Was this translation helpful? Give feedback.
-
We do not; in fact the spec explicitly forbids this.
It does not illustrate that need, nor did I intend it to. I explicitly said the client could "split it into a pure GraphQL query (e.g. |
Beta Was this translation helpful? Give feedback.
-
|
@leebyron @benjie @IvanGoncharov @BoD @twof @michaelstaib @sachee @fotoetienne @yaacovCR @joeynenni |
Beta Was this translation helpful? Give feedback.
-
Overview of IDLs in general
Interface Definition/Description Languages are widely used for describing APIs. There are commonly shared expectations about an IDL and their use. Since IDL is Interface Description Language, the IDL file is expected to completely describe the interface. Meaning, an IDL file is all parties need to know to communicate with each other.
Example: .proto file in gRPC is used to generate, models, client and server stubs in a language of choice. IDL file is a 'source of truth' for an API
The other important point - IDL file is public, all its info is for sharing between the parties. There are no secret parts that 'server cannot share with clients'.
Situation with GraphQL's SDL
In GraphQL things are not clear.
GraphQL SDL (type system/schema definition language) is an IDL for GraphQL (we state it explicitly).
Quote from spec:
So, there's SDL, may be used for something. Is it 'source of truth', complete description? not clear.
Then you read about Introspection, and discover that introspection returns less info than there can be in SDL file. It does not return 'applied attributes'. Seems strange.
A typical expectation for a new-comer would be: SDL and Introspection provides the same information, both a 'source of truth'. SDL is for humans, Intro for tools.
But in GraphQL its different. So I asked questions. Here are the answers I got from one of old timers in this WG:
Q: Why introspection and SDL do not match? What is a true description of API, source of truth?
A:
Later reading thru some discussions, I learned that exposing more through Introspection brings the risk exposing too much, some server-side secret, that is .... in server-side SDL. There is a server-side only SDL, with atributes and all. It is what we describe in the spec, full SDL, but client would never see it. If it is not shared, it is NOT part of communication protocol! I see some kind of 'hidden agenda' here.
Problem Statement
Problems:
Suggestion
SDL file for humans, Introspection for tools/apps
Beta Was this translation helpful? Give feedback.
All reactions