Consider simplifying the specification?

[martinbonnin]

There has been a lot of discussion lately about how to handle the Accept header and response Content-Type.

2 recent examples:

• Bump watershed to 2030? #322
• Require support of application/graphql-response+json by servers #327

The current draft of the specification splits the "response" section in 2 depending on whether the content-type is application/json or application/graphql-response+json. There is also a watershed in both the request section and the response section.

I understand the original (circa 2018) intent of the spec was to accurately describe the status quo and provide a foundation to build upon. As time has passed, we have realized the need to change this status quo, most importantly around Content-Types and HTTP status codes.

The result is we have now an hybrid spec with older (but still used) parts as well as newer (mostly unused but desired) parts. And a watershed to signal the transition.

All of this is non-negligeable mental load and will require some amount of education.

Since this is a new spec, we have a unique opportunity at a blank page and starting from that complexity feels a bit like a missed opportunity. It's not like we would make a breaking change, there was just nothing before!

What would be anyone's toughts if we simplified the specification to only mention the target (desired) end state?

It doesn't mean that servers would stop working. Old software would technically become non-compliant but implementers can decide to adopt the new specification on their own timeline. Probably for the major frameworks out there we can even reach out and make sure this happens before the actual spec release.

The spec could also add a non-normative note along the lines of below to help implementers who still want to maintain backward compatibility:

Prior to this specification, it was common practice to use the mime type of application/json and return a status code of 200 
no matter the contents of the response. There were also very few implementations that would return other status codes in 
the 4xx and 5xx range on errors.

We recommend that client implementations should check for the application/json  header for the foreseeable future and handle
it less strictly, until server implementations had time to adopt this specification.

Similar, server implementations might want to answer requests for an application/json differently, albeit the timeframe for 
migration here might be much shorter. 

In the long run, it's less complexity for everyone and also a clearer message for the community at large and non-GraphQL experts. Any thoughts? @benjie @Shane32 @enisdenjo

[Shane32]

I'm in favor. Perhaps we could release an appendix stating the specification for legacy compatibility. It would be out of the main spec, an optional feature. We could recommend compliance until at least 2030, as a guideline for servers to follow.

With this suggestion, minimal server implementations need not support application/json responses while still meeting spec.

[benjie]

I'm not super keen on this, but I understand the drive. We should note that doing this will likely push the release of the spec back further since the current version is essentially approved pending the security work, and the security work will be required either way, so this is just additional work.

[enisdenjo]

Sounds good to me, but I'd like (even prefer) to avoid pushing the spec even further in the future (following what @benjie said).

[Shane32]

the current version is essentially approved pending the security work

Can we simply finish the pending security work and release it as-is without any changes in regards to the watershed? Cleanup can occur after release. (It would be functionally equivalent since the watershed date has already passed.)

[martinbonnin]

A few comments, in order.

the current version is essentially approved pending the security work

@benjie how do we document approval of a given spec/RFC? Do we have a formal process somewhere maybe?

Sounds good to me, but I'd like (even prefer) to avoid pushing the spec even further in the future

@enisdenjo can you ellaborate? Sounds like you would rather release the spec as is? Or simplify now and avoid ulterior changes?

Cleanup can occur after release.

Right. While it's technically true, the messaging isn't going to be as strong. In this social media world, our audience has limited attention and the simpler the message, the more people it can reach IMO.

[enisdenjo]

I mean the spec progression is already slow and I'd like to avoid slowing it down further, thats the only thing. But, I do in fact like the change!

Specifically because I see the spec's full potential in public GQL APIs where you need consistent and expected communication with clients. In-house/private APIs gain almost no benefit by complying with the spec (aside from the security aspects) - if they work for the user, why change...

[Shane32]

Agree! Also, in-house/private APIs may have long term benefits from any spec advances by requiring less custom implementations and being able to rely more on well-tested public implementations, thus requiring less maintenance over time. Most of my APIs fall into this scenario (in-house / private use). Over time I’ve been pleased to continually reduce the amount of custom code required to meet our GraphQL-related objectives. As an example, the persistent document draft spec is now included in GraphQL.NET and need not require custom middleware to implement.