What's new in API version `2023-10`

[rachelatmonday (Rachel)]

We released API version 2023-10 on July 1! It features many new and exciting updates, as well as a handful of breaking changes (read more about API versioning here).

We put together this guide (complete with a detailed explanation for each change) to help make the transition to the new version easier! Check out all of the changes below, and make sure to click on each item’s respective link to see the full details about each update

After checking out the updates, we would love to hear from you! Your opinions and feedback are vital to building, maintaining, and improving our API. Feel free to submit our feedback form or post any questions in the comments below!

Here’s what’s new

Breaking changes

• Removed the deprecated items field on boards queries, replaced it with items_page

• Removed the deprecated items field on groups queries, replaced it with items_page

• New column values fields and typed column values

• Removed the deprecated items_by_column_values and items_by_multiple_column_values objects, replaced them with items_page_by_column_values

• The column_type field on the create_column mutation is now a required field

• Empty parentheses are no longer supported

• Quotation marks for strings are now required

• Removed the deprecated pos fields on boards and columns queries

• The type field on columns queries has changed from String! to ColumnType!

• Deprecated the newest_first argument on boards queries

• Many of the ID arguments and fields have changed from Int to ID type

• Text field returns empty results for mirror, dependency, and connect boards columns

Non-breaking changes

• New move_item_to_board mutation

• New linked_items field on items queries

• New edit_update and delete_update webhooks

• The value argument in the change_simple_column_value mutation is now nullable

• The complexity of the text field for mirror, link, and dependency columns increased

[basdebruin]

hi @rachelatmonday

Thank you for the headsup. As there a a number of breaking changes we need to test all our apps. I’m a little puzzled what the best way is to start testing.

• is there any API versioning support in the API Playground and if so, how can we set the version? Tried to set the header in the API Playground without succes.
• how do we use versioning if we do use the mondayClient from the monday-sdk-js npm packages (see below)

  static async getBoardTitle(logInfo, token, boardId) {
    try {
      const mondayClient = initMondayClient({ token });

      const query = `query getBoardTitle ($boardId: Int) {
        boards (ids: [$boardId]) {
          name
          description
        }
      }`;
      var variables = { boardId };
      var response = await mondayClient.api(query, { variables });
      return response.data.boards[0] ? { data: response.data.boards[0] } : { data: false };
    } catch (err) {
      return { error: { reason: err.message } };
    }
  }

[MaxTheBean (Maxime TheBean)]

Hi,

@basdebruin If I take a look at the monday client source here, I see you can either pass the API version in the constructor, or use the setApiVersion method after the fact.

@rachelatmonday In our case, we are using the sdk-js on the front-end without passing any token. The sdk then fallsback to sending a message to the iFrame parent:

api(query, options = {}) {
    const params = { query, variables: options.variables };
    const token = options.token || this._apiToken;
    const apiVersion = options.apiVersion || this._apiVersion;

    if (token) {
      return mondayApiClient.execute(params, token, { apiVersion });
    } else {
      return new Promise((resolve, reject) => {
        this._localApi("api", { params })
          .then(result => {
            resolve(result.data);
          })
          .catch(err => reject(err));
      });
    }
  }

This _localApi method does not support (or implement) the apiVersion parameter.

What would be your suggested solution to this?

Kind regards,
Maxime

[Yoni_Leivn (Yoni levin)]

When using API Playground there is an icon of “time going backwards” that allow you to change versions. Here is an example:

[basdebruin]

Hi Maxime,

My integration is backend, not frontend. I don’t see how to set the API version setAPIVerion in:

 const initMondayClient = require("monday-sdk-js");     

  static async getApiVersion(token) {

      const mondayClient = initMondayClient({ token });
      mondayClient.setToken(token);

      const query = `query{version {kind value} }`;
      var variables = {};
      var response = await mondayClient.api(query, { variables });
      logger.debug({ reason: "testing api version", myVersion: response });
  }

[MaxTheBean (Maxime TheBean)]

Hi @basdebruin,

First off, make sure your monday-sdk-js dependency is up to date, the API versioning is rather new.

If you want to set the API version, you can do any of the following:

For every subsequent uses of the client:

const mondayClient = initMondayClient({ token, apiVersion: "2023-10" });

or

const mondayClient = initMondayClient({ token });
mondayClient.setApiVersion("2023-10");

For a single API call:

const mondayClient = initMondayClient({ token });
...
var response = await mondayClient.api(query, { variables, apiVersion: "2023-10" });

Kind regards,
Maxime

[basdebruin]

Many thanks, I did tried that but probably missed a restart of Node. Works like a charm.

[rachelatmonday (Rachel)]

Thanks for the solution @MaxTheBean! I am checking with the team to find a solution to your question above and will update you on this thread ASAP!

@basdebruin Thanks for the questions. We plan to also add more info about how to access the different versions in the documentation, so this is very timely. Let us know if you have any other questions while testing!

[Pask]

Hi @rachelatmonday,
Could you please pass on that the export of the monday-sdk-js is also not up to date with the apiVersion parameter and setApiVersion function?

@MaxTheBean and I had to dig into the source code to find out how to pass the API version because the TypeScript doesn’t declare the apiVersion parameter for the init and doesn’t export a setApiVersion function.

import { ClientData } from './client-data.interface';
import { ClientExecute } from './client-execute.interface';
import { ClientApi } from './client-api.interface';

export as namespace mondaySdk;

type MondayClientSdk = ClientData & ClientExecute & ClientApi;

interface MondayServerSdk {
    setToken(token: string): void;

    api(query: string, options?: Partial<{ token: string, variables: object, apiVersion: string } >): Promise<any>;

    oauthToken(code: string, clientId: string, clientSecret: string): Promise<any>;
}

declare function init(
    config?: Partial<{
        clientId: string;
        apiToken: string;
    }>,
): MondayClientSdk;

declare function init(
    config?: Partial<{
        token: string;
    }>,
): MondayServerSdk;

export = init;

Thanks!

[rachelatmonday (Rachel)]

Thanks for letting me know @Pask, and another thanks to the two of you for doing it and sharing the answers here!

I just sent this to our API team

[Yoni_Leivn (Yoni levin)]

Adding to what Rachel posted, we would love to hear from you any feedback related to new updated API. Either bug or improvements suggestion.
Feel free to submit it in this form: Preview '2023-10' Version Feedback Form

[Pask]

Hi @rachelatmonday ,

Thank you so much! Is there an online task we can follow or have an idea of when/if changes will be done? We’d be glad to give the changes a go and provide feedback once the API version is available for front-end calls.

Kind regards,

[rachelatmonday (Rachel)]

Hey @Pask,

The devs just pushed a change today that should take care of it. Feel free to test it when you get a chance, and let us know if you have any other issues!

Thank you

[Pask]

Hi again @rachelatmonday,

I can confirm the TypeScript changes are done. Thank you so much .
Looking at the code and testing it, I noticed the issue @MaxTheBean raised isn’t resolved.

For context; we call the api function of the Client in the front-end after initializing it with an apiVersion. But the api function doesn’t pass on the apiVersion parameter to the _localApi execution, which is called because we do not use tokens in the front-end.

From the source;

// From monday-sdk-js/src/client.js
  api(query, options = {}) {
    const params = { query, variables: options.variables };
    const token = options.token || this._apiToken;
// I can confirm this is set correctly while debugging.
    const apiVersion = options.apiVersion || this._apiVersion;

    if (token) {
      return mondayApiClient.execute(params, token, { apiVersion });
    } else {
// Because we are in the front-end, we don't pass a token, so the code ends up here
      return new Promise((resolve, reject) => {
// The params here do not include the apiVersion
        this._localApi("api", { params })
          .then(result => {
            resolve(result.data);
          })
          .catch(err => reject(err));
      });
    }
  }

Do you have any feedback from your Dev team about this? Ideally an estimate of when we can expect to test the new APIs?

Kind regards,

[rachelatmonday (Rachel)]

Hi @Pask,

You should now be able to use the apiVersion param in both client and server!

[Pask]

Hi @rachelatmonday,

We can specify the apiVersion in the client, but the SDK’s code requires the use of a token to actually use the apiVersion we provide (as shown in the snippet of my last post).

In our app those calls are done on the front-end and thus, we do not use tokens.

Even in the latest released version of the SDK (0.4.2) that dates from 9 hours ago, we cannot run client API calls with an apiVersion configured.

[rachelatmonday (Rachel)]

@Pask okay makes sense. I am hoping to get an update for you in the next few days

[rob (Roberto Tremonti)]

@rachelatmonday

New linked_items field on items queries

Hey @rachelatmonday
What’s the point of introducing the linked_items field when you need to specify the connected board column id and the connected board id?
You still need to run one query to get the required ids, then you can run the query to get the new linked_items array.

What I’m asking for since ages and what would reduce the API calls considerably is a way to get all the mirrored column infos in just one query.
Currently it’s a nightmare to know the (1) item id, (2) board id, (3) column id, (4) column type, (5) column text, (6) column value of mirrored columns in just one query.

[rob (Roberto Tremonti)]

@Yoni_Leivn

When using API Playground there is an icon of “time going backwards” that allow you to change versions.

This function is available in the generic API playground (https://monday.com/developers/v2/try-it-yourself), not in the one directly linked to your account (https://my_company.monday.com/apps/playground).

[Yoni_Leivn (Yoni levin)]

Hi @rob
There are several reasons why board_id and column_id is required in linked_items:

1. In one linked column can be connected to 5 different boards
2. In one board there could be dozens of linked columns (aka Board Relation columns).
3. One item in one column can be connected to hundreds of items.
   In the world where our boards can contain hundreds of thousands items query all linked items for single item is no longer valid options.

In fact to understand linked board id and linked column id you can run one simple query:

query {
  boards(ids:1721464578){
    columns(types:[board_relation]){
      id
      settings_str
    }
  }
}

which will return all linked columns with ID and linked board ids:

{
  "data": {
    "boards": [
      {
        "columns": [
          {
            "id": "connect_boards",
            "settings_str": "{\"allowCreateReflectionColumn\":false,\"boardIds\":[534611516,3098129846]}"
          },
          {
            "id": "connect_boards_1",
            "settings_str": "{\"allowCreateReflectionColumn\":false,\"boardIds\":[4287992714,3748432847]}"
          }
        ]
      }
    ]
  },
  "account_id": XXXXXX
}

Besides, in the future, we want to make those arguments optional but it will come with hard pagination enforcement.

In general we created a form to submit a feedback about new API: https://forms.monday.com/forms/7e8549695cf4fc5ce10dc934ef566ce0?r=use1
So if you have any more feedback we are happy to get it and try to incorporate it in future releases.