All API documentation should be rewritten to use GraphQL variables where possible

[dvdsmpsn (David @ David Simpson Apps)]

There are so many people in this forum trying to debug string concatenation and badly escaped JSON in GraphQL queries.

If the documentation provided only the best quality examples of how to use GraphQL variables, it would save everybody’s time and lead to a much better developer experience.

some examples:

• Next_items_page - #4 by codyfrisch
• Next_items_page - #6 by codyfrisch
• PHP Developers have any luck inserting a item into a group from a webform? - #3 by dvdsmpsn

Btw: I’m not saying the docs are bad, just if there’s one example where graphQL variables could be used and they are not, then that’s one too many.

Just one example of string concatenation is enough to teach you the wrong way, especially if it’s just adding a board_id to a simple query.

Do you take pull requests on the docs?

Cc: @anon29275264 @dipro @OmerK

[OmerK (Omer Koort)]

Hey David,
That’s a great suggestion actually. noted!
For today, it would make it more complicated to copy&paste examples into the API playground.
So for now we would reccomend to use the AI assitant to convert the examples into different languages.

Lmk if it helps.

[dvdsmpsn (David @ David Simpson Apps)]

Thanks. Actually, it’s very easy to copy and paste graphql variables into the playground.

Check:

[anon29275264]

Just a note, over the last couple years, at least 20 times (an estimate of my OWN responses only) the solution to a thread has been to use GraphQL variables instead of string concatenation or string templates.

Also the javascript documentation examples are not written using the monday-graphql-api module, (or the now deprecated for API use, monday-sdk-js) which leads to confusion. The example use fetch and specify the token, and adds complexity vs using the seamless authentication supported by the official api/sdk modules. These examples then lead developers to think they have get a token, so they implement OAuth2 and store tokens. Instead of just using the seamless authentication. While using seamless is documented - most devs will not read the documentation start to finish, they will look at the examples and iterate on those. If the examples demonstrate bad practices, developers will implement and iterate on bad practices. This will lead to lower quality apps for the platform.

Oddly some of the JavaScript examples do use variables - but for column mutations they use a string for the variable used for column_values instead of showing an object being serialized using JSON.stringify(). This leads devs into using string concatenation or templates yet again!

Lastly, all the bad code examples are feeding the AIs. Garbage in, garbage out. This means AI is just going to propagate crap code further

[dvdsmpsn (David @ David Simpson Apps)]

Here’s another graphql string concatenation error

Having a GraphQL parsing error:

Trying to update Monday,con columns using PHP file and everything thin gh I;ve tried, and I’ve enlisted Gemini AI, fails. Any ideas on how rto make this update work? I send: $query = 'mutation $query = ‘mutation updateItemData{change_multiple_column_values(board_id:’ . $boardId . ‘,item_id:’ . $itemId . ‘,column_values:’ . $formattedColumnValuesForGraphQL . ‘){id name column_values{id value type}}}’; Which produces this mutation: mutation updateItemData { change_multiple_column_values ( b…

Please fix the documentation so that people have the very best start and don’t make silly mistakes.