Dokumentacja dla programistów

Migracja do wersji 2025-04

Aktualizacja 2026-09-06

15 lutego 2026 r. oficjalnie rozpoczniemy wycofywanie wersji API 2024-10 i 2025-01. Po tej dacie wszystkie wywołania API korzystające z tych wersji będą automatycznie kierowane do wersji 2025-04.

Może to spowodować nieoczekiwane działanie i błędy funkcji. Przed tym terminem zaktualizuj wywołania API do wersji 2025-04 lub nowszej.

Aby ułatwić migrację, podzieliliśmy istotne zmiany na trzy sekcje:

Zmiany powodujące niezgodność :rotating_light:: ta sekcja opisuje zmiany powodujące niezgodność i poprawki wprowadzone w wersji 2025-04. Zapoznaj się z nią niezależnie od tego, czy korzystasz z wersji 2024-10, czy 2025-01.
Dodatkowe zmiany powodujące niezgodność :rotating_light:: ta sekcja opisuje zmiany powodujące niezgodność i poprawki wprowadzone w wersji 2025-01. Dotyczy tylko użytkowników wersji 2024-10; użytkownicy wersji 2025-01 mogą ją pominąć.
Zmiany niepowodujące niezgodności :white_check_mark:: oprócz zmian powodujących niezgodność wersja 2025-04 wprowadza wiele nowych możliwości API. Nie trzeba niczego aktualizować w ramach migracji, ale zalecamy zapoznanie się z tymi zmianami, aby poznać pełne możliwości API.

Zmiany powodujące niezgodność (wszyscy użytkownicy) :rotating_light:

Użytkownicy wersji 2025-01 i 2024-10 muszą uwzględnić następujące zmiany:

Zaktualizowany format błędu wyczerpania limitu złożoności

Zaktualizowaliśmy format błędu wyczerpania limitu złożoności, aby zapewnić większą spójność błędów API.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy:

rygorystycznie sprawdzają odpowiedzi i nie dopuszczają dodatkowych pól,
używają testów snapshot i oczekują stałej struktury odpowiedzi,
ręcznie analizują konkretne pola odpowiedzi.

Jak przeprowadzić migrację?

Zaktualizuj logikę, która opierała się na poprzednim formacie błędu.
Sprawdź, jak klient obsługuje rozszerzenia i kody błędów GraphQL oraz zagnieżdżone pola.
Zaktualizuj typowane modele błędów, aby uwzględniały nową strukturę.

Przykład

New complexity budget exhausted error format

{  
    "errors": [  
        {  
            "message": "Complexity budget exhausted",  
            "extensions": {  
                "code": "COMPLEXITY_BUDGET_EXHAUSTED",  
                "complexity": 6182,  
                "complexity_budget_left": 100,  
                "complexity_budget_limit": 5000000,  
                "retry_in_seconds": 60,  
                "status_code": 429  
            }  
        }  
    ]  
}

Nowe błędy mutacji `create_webhook`

Mutacja create_webhook zwraca teraz błędy InvalidArgumentException, gdy:

nie można znaleźć identyfikatora tablicy,
przekazano identyfikator tablicy podelementów.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy:

przekazują identyfikatory tablic bez sprawdzania, czy istnieją,
tworzą webhooki na tablicach podelementów,
korzystają z ogólnej obsługi błędów i nie rozróżniają obecnie nieprawidłowych argumentów.

Jak przeprowadzić migrację?

Sprawdź, czy identyfikatory tablic istnieją, zanim przekażesz je do mutacji.
Nie próbuj tworzyć webhooków na tablicach podelementów.
Zaktualizuj obsługę błędów, aby uwzględniała nowe błędy.

Przykłady

New board not found error

{
  "data": {
    "create_webhook": null
  },
  "errors": [
    {
      "message": "Board not found",
      "locations": [
        {
          "line": 1,
          "column": 10
        }
      ],
      "path": [
        "create_webhook"
      ],
      "extensions": {
        "code": "InvalidArgumentException",
        "status_code": 200,
        "error_data": {
          "board_id": 1186075578
        }
      }
    }
  ]
}

New subitems board ID error

{
  "data": {
    "create_webhook": null
  },
  "errors": [
    {
      "message": "Creating webhook on subitems board isn't allowed",
      "locations": [
        {
          "line": 1,
          "column": 10
        }
      ],
      "path": [
        "create_webhook"
      ],
      "extensions": {
        "code": "InvalidArgumentException",
        "status_code": 200,
        "error_data": {
          "board_id": 118607557
        }
      }
    }
  ]
}

Pole `renewal_date` może mieć wartość null w zapytaniach dotyczących subskrypcji aplikacji

Pole renewal_date jest teraz opcjonalne (zmieniono typ z String! na String) i zwraca null w przypadku nieaktywnych subskrypcji.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność w aplikacjach, które:

korzystają z rygorystycznych systemów typów i oczekują, że renewal_date będzie ciągiem znaków,
używają renewal_date do sortowania, filtrowania lub wyświetlania bez obsługi wartości null,
statycznie generują typy GraphQL i nie zaktualizowały ich.

Jak przeprowadzić migrację?

Zaktualizuj typy schematu, aby pole renewal_date mogło przyjmować wartość null.
Dodaj sprawdzanie wartości null w logice, która zakłada, że renewal_date zawsze ma wartość.
Wygeneruj ponownie typy GraphQL.

Zmiany w zapytaniu o podelementy

Zmieniliśmy sposób zwracania i pobierania podelementów za pomocą istniejącego zapytania:

Pusta odpowiedź dla podelementów z usuniętej tablicy: zapytanie o podelementy usuniętej tablicy zwróci teraz pustą odpowiedź.
Limit współbieżności pola podelementów: podczas pobierania pola podelementów wprowadzono nowy limit współbieżności na poziomie pola. Po przekroczeniu limitu zwracany jest błąd.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy wcześniej pobierali podelementy elementów należących do usuniętych tablic lub dużą liczbę podelementów w jednym żądaniu.

Jak przeprowadzić migrację?

Sprawdzaj, czy zapytanie o podelementy usuniętej tablicy zwraca pustą odpowiedź, i obsługuj taki wynik w interfejsie lub logice.
Użyj argumentu page, aby pobierać wyniki strona po stronie.
Obsługuj wartości null podelementów w kodzie klienta, aby zapobiec błędom.

Przykład

Response when subitems field level concurrency limit is exceeded

{
  "data": {
    "items": [
      {
        "subitems": null
      }
    ]
  },
  "errors": [
    {
      "message": "Concurrency limit exceeded for the field",
      "locations": [
        {
          "line": 1,
          "column": 25
        }
      ],
      "path": [
        "items",
        0,
        "subitems"
      ],
      "extensions": {
        "code": "FIELD_LIMIT_EXCEEDED",
        "status_code": 429,
        "retry_in_seconds": 15,
        "error_data": {
          "entity": "subitems"
        }
      }
    }
  ]
}

Zmiany we właściwości `column_type` w błędach `ColumnValueException`

Błędy ColumnValueException zwracają właściwość column_type, która wskazuje typ kolumny powodującej błąd. Wcześniej ta właściwość zwracała typ kolumny z dopisanym słowem „Column”:

Na przykład: „ColorColumn”, „StatusColumn”, „DateColumn”

Po tej aktualizacji właściwość column_type zwraca sam typ kolumny, bez dopisanego słowa „Column”.

Na przykład: „color”, „status”, „date”

Pełną listę obsługiwanych typów kolumn znajdziesz tutaj.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy:

analizują ciąg column_type w błędach ColumnValueException,
używają wartości column_type w swojej logice,
zakładają, że format wartości to ColorColumn lub StatusColumn, na przykład w walidacji po stronie klienta lub logice awaryjnej.

Jak przeprowadzić migrację?

Zaktualizuj logikę, która sprawdza wartości column_type.
Jeśli korzystasz z warstwy mapowania, zaktualizuj mapowania, aby używały nowych ciągów określających typ.

Przykład

New format of the relevant `ColumnValueException` error

{
  "message": "invalid value - label does not exist in column. Please check our API documentation for the correct data structure for this column. https://developer.monday.com/api-reference/docs/change-column-values",
  "locations": [
    {
      "line": 1, 
      "column": 10
    }
    ],
  "path": [
    "change_column_value"
    ],
  "extensions": {
    "code": "ColumnValueException", 
    "status_code": 200, 
    "error_data": {
      "column_type": "color", 
    }
  }
}

Nowy, unikatowy identyfikator żądania we wszystkich odpowiedziach API

Wszystkie odpowiedzi API zawierają teraz unikatowy identyfikator żądania. Ułatwia on mierzenie wydajności, śledzenie pełnego cyklu życia żądania w różnych usługach oraz rozwiązywanie problemów.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy:

rygorystycznie sprawdzają odpowiedzi i nie dopuszczają dodatkowych pól,
używają testów snapshot i oczekują stałej struktury odpowiedzi,
ręcznie analizują konkretne pola odpowiedzi.

Jak przeprowadzić migrację?

Zaktualizuj schematy odpowiedzi lub typy klienta, np. typy GraphQL i interfejsy TypeScript, aby dopuszczały nowe pole request_id.
Zaktualizuj snapshoty, aby uwzględniały to nowe pole, jeśli ma to zastosowanie.
Upewnij się, że obiekt extensions jest dozwolony lub bezpiecznie ignorowany.

Przykład

Valid response with the new `request_id` field

{
  "data": {
    "timeline_item": null
  },
  "errors": [
    {
      "message": "User is not allowed to read timelineItem.",
      "locations": [
        {
          "line": 1,
          "column": 2
        }
      ],
      "path": [
        "timeline_item"
      ],
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ],
  "extensions": {
    "request_id": "152b0dgb-d38c-067c-9f79-dd0c0d7238ed"
  }
}

Zmienne trzeba teraz przesyłać jako obiekt JSON

Nie można już przesyłać zmiennych jako ciągu JSON. Trzeba przesyłać je jako prawidłowy obiekt JSON. Każde zapytanie, w którym zmienne są przekazywane jako ciąg JSON, spowoduje błąd.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana powoduje niezgodność u wszystkich użytkowników i we wszystkich zapytaniach, w których zmienne były wcześniej przesyłane jako ciągi znaków.

Jak przeprowadzić migrację?

Zamień ciągi JSON ze zmiennymi na prawidłowe obiekty JSON.

Przykład

Poniższy przykład przedstawia to samo zapytanie przed zmianą i po niej:

Valid: JSON object format

{
  "query": "query GetBoardItems($boardId: [ID!]) { boards(ids: $boardId) { items_page(limit: 1) { cursor items { id subitems { id name column_values { column { title } text ... on MirrorValue { display_value } ... on BoardRelationValue { linked_item_ids linked_items { name } } } } } } } }",
  "variables": {
    "boardId": 1234567890
  }
}

Invalid: JSON string format

{
  "query": "query GetBoardItems($boardId: [ID!]) { boards(ids: $boardId) { items_page(limit: 1) { cursor items { id subitems { id name column_values { column { title } text ... on MirrorValue { display_value } ... on BoardRelationValue { linked_item_ids linked_items { name } } } } } } } }",
  "variables": "{\"boardId\":1234567890}"
}

Pole z wartością null w kolumnach łączących tablice, zależności i podzadań

Pole value w kolumnach łączących tablice, zależności i podzadań będzie teraz zwracać null zamiast identyfikatorów połączonych elementów i daty ich ostatniej aktualizacji.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana powoduje niezgodność u

Jak przeprowadzić migrację?

Pobierz brakujące dane bezpośrednio z pól linked_items i linked_item_ids.

Przykład

Query using `linked_items` and `linked_item_ids` fields

query {  
  boards(ids: 1234567890) {  
    items_page {  
      items {  
        column_values(ids: ["connect_boards"]) {  
          value  
          ... on BoardRelationValue {  
            linked_item_ids  
            linked_items {  
              name  
              updated_at  
            }  
          }  
          id  
        }  
      }  
    }  
  }  
}

Response with `linked_items` and `linked_item_ids` fields

{
  "data": {
    "boards": [
      {
        "items_page": {
          "items": [
            {
              "column_values": [
                {
                  "value": null,
                  "linked_item_ids": [
                    "9876543210"
                  ],
                  "linked_items": [
                    {
                      "name": "Item 4",
                      "updated_at": "2023-08-29T15:38:11Z"
                    }
                  ],
                  "id": "connect_boards"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Dodatkowe zmiany powodujące niezgodność (tylko użytkownicy wersji `2024-10`) :rotating_light:

Oprócz zmian opisanych powyżej użytkownicy wersji 2024-10 muszą uwzględnić następujące zmiany powodujące niezgodność, wprowadzone w wersji 2025-01. Użytkownicy wersji 2025-01 mogą pominąć tę sekcję.

Nowe, ujednolicone odpowiedzi błędów zgodne ze standardem GraphQL

Błędy mają teraz spójny format zgodny ze specyfikacją GraphQL. Są zwracane w następującym formacie:

Kod statusu HTTP: w przypadku błędów na poziomie aplikacji odpowiedź będzie miała kod 200 – OK. W przypadku błędów warstwy transportowej zwracane będą inne kody, na przykład 429 – zbyt wiele żądań lub 400 – nieprawidłowe żądanie.
Odpowiedź JSON: treść odpowiedzi będzie zawierać tablicę errors ze szczegółowymi informacjami o każdym błędzie.
Częściowe dane: zapytanie może zwrócić częściowe dane i błędy. W takim przypadku otrzymasz zarówno obiekt data, jak i errors. Jeśli wystąpi błąd dotyczący pola, jego wartością będzie null.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność u użytkowników, którzy:

rygorystycznie sprawdzają odpowiedzi i nie dopuszczają dodatkowych pól,
używają testów snapshot i oczekują stałej struktury odpowiedzi,
ręcznie analizują konkretne pola odpowiedzi.

Jak przeprowadzić migrację?

Zaktualizuj logikę, która opierała się na poprzednim formacie błędu.
Sprawdź, jak klient obsługuje rozszerzenia i kody błędów GraphQL oraz zagnieżdżone pola.
Zaktualizuj typowane modele błędów, aby uwzględniały nową strukturę.

Przykład

Updated error format

{
  "data": [],
  "errors": [
    {
      "message": "User unauthorized to perform action",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "me"
      ],
      "extensions": {
        "code": "UserUnauthorizedException",
        "error_data": {},
        "status_code": 403
      }
    }
  ],
  "account_id": 123456
}

Walidacja zapytań GraphQL bardziej zgodna ze specyfikacją

Wprowadziliśmy ulepszony parser GraphQL, który sprawdza zgodność zapytań ze specyfikacją GraphQL, w tym pod kątem reguł, które wcześniej były ignorowane. Schemat API nie uległ zmianie.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana powoduje niezgodność u wszystkich użytkowników, którzy wysyłają zapytania niezgodne ze specyfikacją GraphQL, w tym zapytania zawierające znak nowej linii w ciągu znaków lub przekazujące null do pola, które nie dopuszcza wartości null.

Jak przeprowadzić migrację?

Korzystaj z udokumentowanego schematu dla każdego typu obiektu, aby tworzyć zapytania zgodne ze specyfikacją GraphQL. Zalecamy też przetestowanie zapytania w środowisku API Playground, aby szybko znaleźć błędy składniowe.

Migracja do wersji 2025-04 - ilustracja 1

Ścisła walidacja kolumn w aplikacjach

Walidacja kolumn jest teraz ściśle egzekwowana w aplikacjach. Nieprawidłowy kod JSON spowoduje błąd ColumnValueException.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana może powodować niezgodność we wszystkich aplikacjach i ich walidacji kolumn.

Jak przeprowadzić migrację?

Użyj formatera JSON, aby sprawdzić format zapytania.

Identyfikator konta nie jest już dołączany do odpowiedzi

account_id nie jest już domyślnie zwracany we wszystkich odpowiedziach.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Zmiana dotyczy użytkowników, którzy pobierali identyfikator konta domyślnie dołączany do odpowiedzi.

Jak przeprowadzić migrację?

Pobierz identyfikator, wysyłając zapytanie o obiekt account.

Przykład

New response without account ID

{
  "data": {
    "boards": [
      {
        "id": "9876543210"
      }
    ]
  }
}

Nowy limit paginacji zapytań `updates`

Zapytanie updates zwraca teraz maksymalnie 100 aktualizacji na stronę. Aby pobrać więcej niż 100, musisz przejść przez kolejne strony za pomocą argumentu page.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Ta zmiana powoduje niezgodność u wszystkich użytkowników, którzy pobierają więcej niż 100 aktualizacji updates na stronę.

Jak przeprowadzić migrację?

Użyj argumentu page, aby pobrać kolejne strony aktualizacji.

Przykład

Using the page argument to paginate through results

query {  
  updates (page: 5) {  
    id  
    text_body  
  }  
}

Zapytania GraphQL trzeba wysyłać w treści żądania

Zapytania GraphQL nie są już akceptowane jako parametry zapytania w adresie URL. Wszystkie zapytania muszą być wysyłane w treści żądania HTTP. W przeciwnym razie wywołanie zakończy się niepowodzeniem.

:mega: Przeczytaj dziennik zmian

Kogo dotyczy ta zmiana?

Zmiana powoduje niezgodność u wszystkich użytkowników, którzy wysyłają zapytania GraphQL jako parametry zapytania w adresie URL.

Jak przeprowadzić migrację?

Zaktualizuj wywołania tak, aby zapytanie znajdowało się w treści żądania, a nie w adresie URL.

Nieprawidłowy przykład (nie zadziała)

https://api.monday.com/v2?query=query { me { id } }

Prawidłowy przykład (zalecany sposób użycia)

Correct query usage

query {  
  me {  
    id  
  }  
}

Zmiany niepowodujące niezgodności :white_check_mark:

Oprócz opisanych wyżej zmian powodujących niezgodność wersja 2025-04 wprowadza też nowe funkcje, które nie powodują niezgodności.
Nie trzeba niczego aktualizować w ramach migracji, ale zalecamy zapoznanie się z tymi zmianami, aby w pełni wykorzystać rozszerzone możliwości API.

Nowy typ page_break w mutacji create_doc_block
Nowa mutacja invite_users
Nowe pole end_date w obiekcie szczegółów subskrypcji aplikacji
Nowa mutacja umożliwiająca aktualizowanie atrybutów użytkownika
Nowe pole max_units w zapytaniach dotyczących subskrypcji aplikacji
Nowy argument max_units w mutacjach ustawiających testowe subskrypcje aplikacji
Nowa możliwość pobierania pól niestandardowych profilu użytkownika
Nowy obiekt account_roles
Nowa możliwość aktualizowania niestandardowej roli użytkownika
Nowy obiekt platform_api umożliwiający pobieranie dziennego użycia API
Nowy obiekt umożliwiający pobieranie danych aplikacji

Mam problem z tym tematem Źródło: developer.monday.com

Migracja do wersji 2025-04

Zmiany powodujące niezgodność (wszyscy użytkownicy) :rotating_light:

Zaktualizowany format błędu wyczerpania limitu złożoności

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Nowe błędy mutacji create_webhook

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykłady

Pole renewal_date może mieć wartość null w zapytaniach dotyczących subskrypcji aplikacji

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Zmiany w zapytaniu o podelementy

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Zmiany we właściwości column_type w błędach ColumnValueException

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Nowy, unikatowy identyfikator żądania we wszystkich odpowiedziach API

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Zmienne trzeba teraz przesyłać jako obiekt JSON

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Pole z wartością null w kolumnach łączących tablice, zależności i podzadań

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Dodatkowe zmiany powodujące niezgodność (tylko użytkownicy wersji 2024-10) :rotating_light:

Nowe, ujednolicone odpowiedzi błędów zgodne ze standardem GraphQL

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Walidacja zapytań GraphQL bardziej zgodna ze specyfikacją

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Ścisła walidacja kolumn w aplikacjach

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Identyfikator konta nie jest już dołączany do odpowiedzi

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Nowy limit paginacji zapytań updates

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Przykład

Zapytania GraphQL trzeba wysyłać w treści żądania

Kogo dotyczy ta zmiana?

Jak przeprowadzić migrację?

Nieprawidłowy przykład (nie zadziała)

Prawidłowy przykład (zalecany sposób użycia)

Zmiany niepowodujące niezgodności :white_check_mark:

Nowe błędy mutacji `create_webhook`

Pole `renewal_date` może mieć wartość null w zapytaniach dotyczących subskrypcji aplikacji

Zmiany we właściwości `column_type` w błędach `ColumnValueException`

Dodatkowe zmiany powodujące niezgodność (tylko użytkownicy wersji `2024-10`) :rotating_light:

Nowy limit paginacji zapytań `updates`