Wersjonowanie to ważny sposób na ciągły rozwój naszego API bez zakłócania istniejących funkcji. Pozwala programistom wprowadzać aktualizacje i ulepszenia, a jednocześnie zachować stabilne i przewidywalne działanie.

Gwarantujemy dostępność co najmniej trzech różnych wersji API równolegle i wydajemy nową wersję co kwartał. Więcej informacji o najnowszych wersjach znajdziesz w informacjach o wydaniach.

Aktualnie dostępne wersje:

Typy wersji

W danym momencie dostępne są co najmniej trzy typy wersji API: kandydat wydania, wersja bieżąca i wersja utrzymaniowa. Dwie z nich są stabilne, a kolejna to niestabilna wersja zapoznawcza.

Dzięki temu każda wersja pozostaje stabilna przez co najmniej sześć miesięcy. Możesz ograniczyć nakład pracy programistycznej, zawsze dołączając do wywołań API nagłówek wersji.

Typ	Opis
Kandydat wydania (RC)	Zapewnia wczesny dostęp do najnowszych funkcji i ulepszeń Niestabilna wersja, której nie należy używać w aplikacjach produkcyjnych Wcześniej znana jako wersja zapoznawcza
Bieżąca	Zawiera wyłącznie poprawki błędów, które nie powodują niezgodności Stabilna wersja, której można używać w aplikacjach produkcyjnych Jest używana domyślnie, jeśli nie podano nagłówka To, co utworzysz z jej użyciem, nie zmieni się przez co najmniej sześć miesięcy Wcześniej znana jako wersja stabilna
Utrzymaniowa	Zawiera wyłącznie poprawki błędów, które nie powodują niezgodności Stabilna wersja, której można używać w aplikacjach produkcyjnych (zalecamy korzystać z niej tylko wtedy, gdy nie możesz na czas przejść na wersję bieżącą) Wcześniej znana jako wersja przestarzała

Dokumentacja

Nasze przewodniki i dokumentacja API zawsze odzwierciedlają schemat bieżącej wersji. Wszystkie nadchodzące aktualizacje i zmiany schematu ogłaszamy w dzienniku zmian API i informacjach o wydaniach. Odpowiednie zmiany oznaczamy też w dokumentacji API (zobacz przykład poniżej).

Cykl życia

Każda wersja przechodzi przez następujący cykl życia:

• Wydanie nowego kandydata wydania (RC) (co kwartał)
• RC --> Bieżąca (po 3 miesiącach)
• Bieżąca --> Utrzymaniowa (po 3 miesiącach)
• Utrzymaniowa --> Wycofana (informacja zostanie ogłoszona z co najmniej 6-miesięcznym wyprzedzeniem)

Harmonogram wydań

Nowe wersje RC są udostępniane stopniowo co trzy miesiące, na początku każdego kwartału, o 00:00 UTC.

Nazwy wersji nie są semantyczne. Wskazują rok i miesiąc, w których dana wersja staje się domyślna i bieżąca. Na przykład bieżąca wersja z lipca, czyli z trzeciego kwartału 2024 roku, nosiłaby nazwę 2024-07.

Nazwa wersji	RC	Bieżąca (domyślna)	Utrzymaniowa	Wycofana
2024-10	1 lipca 2024	1 października 2024	15 stycznia 2025	15 lutego 2026
2025-01	1 października 2024	15 stycznia 2025	1 kwietnia 2025	15 lutego 2026
2025-04	15 stycznia 2025	1 kwietnia 2025	1 lipca 2025	Jeszcze nie ogłoszono*
2025-07	1 kwietnia 2025	1 lipca 2025	1 października 2025	Jeszcze nie ogłoszono*
2025-10	1 lipca 2025	1 października 2025	15 stycznia 2026	Jeszcze nie ogłoszono*
2026-01	1 października 2025	15 stycznia 2026	1 kwietnia 2026	Jeszcze nie ogłoszono*
2026-04	15 stycznia 2026	1 kwietnia 2026	1 lipca 2026	Jeszcze nie ogłoszono*
2026-07	1 kwietnia 2026	1 lipca 2026	1 października 2026	Jeszcze nie ogłoszono*
2026-10	1 lipca 2026	1 października 2026	15 stycznia 2027	Jeszcze nie ogłoszono*
2027-01	1 października 2026	15 stycznia 2027	1 kwietnia 2027	Jeszcze nie ogłoszono*

*Informacja o wycofaniu każdej wersji zostanie ogłoszona z co najmniej sześciomiesięcznym wyprzedzeniem!

Jak uzyskać dostęp do różnych wersji

Możesz uzyskać dostęp do różnych wersji API, dodając nagłówek do żądania HTTP, korzystając z SDK lub używając środowiska API playground.

👍 Podawanie nazwy wersji w żądaniu

Zdecydowanie zalecamy, aby aplikacje produkcyjne podawały nazwę wersji w każdym wywołaniu API. Jeśli tego nie zrobisz, aplikacja zawsze użyje bieżącej wersji. Podanie nazwy wersji zmniejsza ryzyko, że zmiany niezgodne z wcześniejszymi wersjami zakłócą działanie aplikacji, i daje więcej czasu na przejście na nową wersję.

Używanie nagłówka API-Version w żądaniu HTTP

Możesz wybrać wersję API, której chcesz używać, podając jej nazwę w nagłówku API-Version.

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE',
    'API-Version' : '2026-07'
   },
   body: JSON.stringify({
     'query' : 'query{version {kind value} }'
   })
  });

curl --location --request POST 'https://api.monday.com/v2' \
--header 'API-Version: 2026-07' \
--header 'Authorization: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { version { kind value } }"}'

Wszystkie odpowiedzi API zawierają nagłówek API-Version, który wskazuje wersję użytą w danym wywołaniu. Te same informacje możesz uzyskać, odpytując obiekt version. Aby zobaczyć wszystkie dostępne wersje API, możesz odpytać obiekt versions.

Korzystanie z SDK

W przypadku GraphQL JS SDK możesz ustawić wersję API na dwa sposoby: jako wersję domyślną albo dla konkretnego wywołania.

import { ApiClient } from "@mondaydotcomorg/api";

const monday = new ApiClient({
  token: process.env.MONDAY_API_TOKEN,  // required
  version: "2026-07"                    // sets default API version
});

const query = `query { me { id } }`;

const data = await monday.request(query, {
  version: "2026-07"
});

API playground

Możesz też użyć środowiska API playground, aby uzyskać dostęp do różnych wersji API i je testować. Kliknij ikonę zegara ze strzałką wstecz na środku ekranu.

Otworzy się selektor wersji, w którym możesz testować zapytania i mutacje w dowolnej z wymienionych wersji.

Przykłady wersjonowania

Wersjonowanie to skuteczny sposób na ulepszanie API, ale wybór wersji i moment jej użycia mogą być niejasne. Przygotowaliśmy przykładowe scenariusze, które pomogą Ci lepiej zrozumieć ten proces.

1. Ogłaszamy wydanie nowego API o nazwie new_API w wersji 2024-01. Możesz uzyskać dostęp do new_API od razu po wydaniu 2024-01 jako wersji RC, podając 2024-01 w nagłówku API-Version. Jeśli nie dodasz nagłówka API-Version, wywołanie automatycznie użyje bieżącej wersji i otrzymasz błąd informujący, że to pole nie istnieje.
2. Ogłaszamy wycofanie pola example w wersji 2023-07. Możesz korzystać z pola example do 15 stycznia 2024 roku, kiedy wersja 2023-07 zostanie wycofana. Gdy zaczniesz podawać w żądaniu 2024-04, stracisz dostęp do pola example.

Ważne pojęcia

Wersjonowanie API może się różnić, dlatego często używane pojęcia mogą mieć w różnych przypadkach nieco inne znaczenie. W tej sekcji wyjaśniamy najważniejsze pojęcia, a przede wszystkim dokładnie opisujemy, co oznaczają.

Pojęcie	Opis
Stabilna	Oznacza, że wersji można niezawodnie używać w środowisku produkcyjnym. Obejmuje wyłącznie poprawki błędów, regresji i krytycznych problemów, które nie powodują niezgodności.
Domyślna	Wersja używana, gdy w wywołaniu API nie podano nagłówka ani nagłówka default.
Niestabilna	Oznacza, że nie można niezawodnie używać wersji w środowisku produkcyjnym. Obejmuje zarówno zmiany powodujące niezgodność, jak i te, które jej nie powodują.
Wycofana	Oznacza, że wersja nie jest już obsługiwana. Wszystkie wywołania wykonane z użyciem wycofanej wersji będą korzystać z wersji utrzymaniowej.
Nazwa wersji	Unikalny identyfikator wersji (np. 2023-10). Zalecamy podawanie nazwy wersji w wywołaniach.
Typ wersji	Typ wersji: release-candidate, current lub maintenance.

Rozwiązywanie problemów

Masz pytania dotyczące wersjonowania? Czytaj dalej, aby poznać częste problemy i dowiedzieć się, jak je rozwiązać.

Nieobsługiwane wersje

• Każde żądanie dotyczące wycofanej wersji API użyje wersji utrzymaniowej. Jeśli zażądasz wersji, która nie istnieje (np. 2024-02 zamiast 2024-01), zostanie użyta bieżąca wersja.

Nieprawidłowe żądania

• Jeśli żądanie ma nieprawidłowy format (np. 2023 zamiast 2023-04), otrzymasz błąd InvalidVersionException. Sprawdź harmonogram wydań, aby zobaczyć nazwy wszystkich wersji i upewnić się, że podajesz je w prawidłowym formacie.
• Jeśli w wywołaniu API użyjesz pola, które nie istnieje w określonej wersji, otrzymasz błąd informujący, że to pole nie istnieje (zobacz poniżej). Upewnij się, że używasz zaktualizowanej wersji - podaj jej nazwę w wywołaniu.

{
  "errors": [
    {
      "message": "Field 'new_field' doesn't exist on type 'Boards'",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "query",
        "boards",
        "new_field"
      ],
      "extensions": {
        "code": "undefinedField",
        "typeName": "Boards",
        "fieldName": "new_field"
      }
    }
  ],
  "account_id": 1
}