Słownik

Każde wywołanie /rest/ wymaga nagłówka LinkedIn-Version w formacie YYYYMM

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •8 min czytania
Każde wywołanie /rest/ wymaga nagłówka LinkedIn-Version w formacie YYYYMMKażde wywołanie /rest/ wymaga nagłówka LinkedIn-Version w formacie YYYYMM

TL;DR, szybka odpowiedź

8 min czytania

LinkedIn co miesiąc wydaje nowe wersje Marketing APIs pod ścieżką bazową /rest/, a każde wywołanie musi wskazać wersję w nagłówku, bo najnowsza nie jest stosowana domyślnie. Wartość ma sześć cyfr w formacie YYYYMM, np. 202608. Brak nagłówka daje 400 VERSION_MISSING, a wycofana wersja 426 NONEXISTENT_VERSION. Każda wersja jest wspierana przez co najmniej rok. Osobny nagłówek X-Restli-Protocol-Version musi mieć wartość 2.0.0, bo bez niego żądanie wraca do protokołu 1.0 i innej składni zapytań.

Czym jest nagłówek LinkedIn-Version?

Każde wywołanie https://api.linkedin.com/rest/ zawiera nagłówek LinkedIn-Version, a LinkedIn akceptuje dla niego tylko jeden format wartości: sześć cyfr, YYYYMM. Dokumentacja wersjonowania ujmuje to w jednym zdaniu: "Include a request header with the key Linkedin-Version and set the value to the version (format: YYYYMM) to correspond with the documentation version you are referencing."

Nagłówek istnieje, bo LinkedIn co miesiąc wydaje nową wersję API i nie zamierza zgadywać, o którą ci chodzi. Z tej samej strony: "LinkedIn expects every versioned API call to specify a version; the latest version is not applied by default."

Pełne żądanie wygląda tak:

curl -X POST 'https://api.linkedin.com/rest/adCampaigns' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Linkedin-Version: 202601' \
--data '{
    "account": "urn:li:sponsoredAccount:123212321",
    "audienceExpansionEnabled": false
}'

Wersjonowanie pojawiło się wraz z nową ścieżką bazową, a nie nową domeną. LinkedIn podaje dokładną datę: "LinkedIn's Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/." Wszystko, co nadal działa na https://api.linkedin.com/v2/, jest starsze od tego schematu i zachowuje się inaczej, o czym mówi ostatnia sekcja.

Jaki format ma wartość wersji?

YYYYMM, czyli czterocyfrowy rok i dwucyfrowy miesiąc, bez separatora i bez dnia. 202601 oznacza wersję opublikowaną w styczniu 2026 roku. Przykład migracji z jednej wersji na drugą, który podaje LinkedIn, to zwykła podmiana ciągu znaków:

-H 'Linkedin-Version: 202501'  to  -H 'Linkedin-Version: 202601'

Ostatnie wartości, skopiowane z tabeli na stronie o wersjonowaniu:

Nazwa wersjiWartość nagłówka
August 2026202608
November 2025"Linkedin-Version": "202511"
October 2025"Linkedin-Version": "202510"
September 2025"Linkedin-Version": "202509"

August 2026, czyli 202608, to wartość, którą strona podaje jako "Latest Version" według ostatniej aktualizacji z 17 sierpnia 2026 roku. Format nie zmienia się z miesiąca na miesiąc, dlatego na tym nagłówku można bezpiecznie oprzeć stopniowe aktualizacje: jedna wartość konfiguracyjna, sześć znaków, jedno wdrożenie.

Jedna niespójność zasługuje na uwagę, bo zmyli każdego, kto dopasowuje tekst błędów. Komunikat o nieaktywnej wersji zawiera ośmioznakowy symbol zastępczy, "Requested version yyyymmdd is not active", choć LinkedIn wymaga sześciu znaków. To jedyne miejsce, w którym pojawia się yyyymmdd. Traktuj to jako literówkę w szablonie komunikatu, a nie drugi dopuszczalny format.

LinkedIn-Version czy Linkedin-Version?

Dokumentacja LinkedIna zapisuje nagłówek jako Linkedin-Version, z małą literą i w drugiej części słowa, na każdej stronie, która o nim wspomina. Tak jest w dokumentacji wersjonowania, Images API, Posts API, Videos API i opisie błędów, a sam komunikat o błędzie mówi "by adding the Linkedin-Version header." Nazwa firmy na tych samych stronach ma zapis LinkedIn.

Nazwy pól nagłówków HTTP nie rozróżniają wielkości liter, więc LinkedIn-Version, Linkedin-Version i linkedin-version trafiają na serwerze do tego samego nagłówka. Pisownia ma znaczenie z węższego powodu: jeśli przeszukasz dokumentację LinkedIna lub kolekcję Postmana pod kątem LinkedIn-Version, niczego nie znajdziesz. Szukaj formy z dokumentacji.

Co się dzieje, gdy nagłówka brakuje lub jest nieaktualny?

To dwa różne błędy z dwoma różnymi kodami statusu, oba opisane w dokumentacji wraz z dokładną treścią odpowiedzi.

SytuacjaStatusKodKomunikat
Brak nagłówka400VERSION_MISSING"A version must be present. Please specify a version by adding the Linkedin-Version header."
Wycofana wersja426NONEXISTENT_VERSION"Requested version yyyymmdd is not active"

Ciekawszy jest kod 426. HTTP 426 to Upgrade Required i LinkedIn używa go dosłownie: żądanie zostało zrozumiane, wskazana wersja już nie istnieje, zaktualizuj nagłówek. To nie 400, nie 410 ani nie 404, więc obsługa błędów, która rozgałęzia się tylko po zakresach 4xx, skieruje go w bezużyteczne miejsce.

Oba błędy pojawiają się, zanim uruchomi się jakakolwiek logika biznesowa. Dane mogą być bezbłędne, a token świeży, a i tak dostaniesz 400, jeśli nagłówka nie ma. Właśnie dlatego nieaktualny nagłówek wersji to tak cichy sposób na awarię zaplanowanych publikacji: w kodzie nic się nie zmienia, mija data wycofania i każde wywołanie zaczyna zwracać 426. Gdy publikowanie z dnia na dzień przestaje działać dla całego konta, bez żadnej zmiany w kodzie, warto sprawdzić listę przyczyn w artykule o zaplanowanych postach na LinkedInie, które przestają działać.

Okablowanie w serwerowni, symbolizujące stabilną wersję API, dzięki której system działa miesiącami bez zmian w kodzie.

Jak długo działa wersja API LinkedIna?

Co najmniej rok. Strona o harmonogramie wydań mówi o tym dwukrotnie: "LinkedIn Marketing API Program publishes new versions monthly, and those versions are supported for a minimum of one (1) year" oraz "These API versions are supported and stable for a minimum of one year before sunset."

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Baner o wycofaniu widoczny w dokumentacji marketingowej to żywy przykład tego zegara: "The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026." Nieco ponad dwanaście miesięcy, zapowiedziane z wyprzedzeniem na każdej stronie.

Roczne minimum ma jeden wyraźny wyjątek. LinkedIn "reserves the right to release a patch version to any API if required for any critical security, privacy issues, or bug fixes", choć określa to prawdopodobieństwo jako minimalne. Gwarancja dotyczy więc tego, że wersja będzie dostępna przez rok, a nie tego, że jej zachowanie przez rok się nie zmieni.

W praktyce oznacza to wpis w kalendarzu, a nie decyzję architektoniczną. Przypnij wersję jawnie, sprawdzaj ją raz w roku i przy tej okazji przeskakuj na najnowszą, bo według LinkedIna migracja do najnowszej wersji daje "the option to wait up to one year before having to migrate again." Warstwę API zbudowaną na tym mechanizmie i to, za co odpowiada każda wersja, opisuje przegląd LinkedIn Marketing API.

Życie numeru wersji
1
Publikacja. LinkedIn co miesiąc wydaje nową wersję pod /rest/, np. 202608.
2
Wsparcie. Wersja pozostaje aktywna przez co najmniej rok od wydania.
3
Zapowiedź. Baner o wycofaniu podaje datę końca, np. 17 sierpnia 2026 dla wersji 202508.
4
Wycofanie. Wywołanie z tą wersją po tej dacie zwraca 426 NONEXISTENT_VERSION.
Dokumentacja podaje datę wycofania na wiele miesięcy przed tym, jak wersja przestanie odpowiadać.

Do czego służy nagłówek X-Restli-Protocol-Version?

Do czegoś zupełnie innego i jest wymagany razem z nagłówkiem wersji, a nie zamiast niego. Posts API wymienia oba jednym tchem: "All APIs require the request header Linkedin-Version: {Version in YYYYMM format}. All APIs require the request header X-Restli-Protocol-Version: 2.0.0."

LinkedIn-Version wybiera, z którego miesiąca zachowanie API dostajesz. X-Restli-Protocol-Version decyduje o sposobie kodowania adresów URL i parametrów zapytań, bo API LinkedIna są zbudowane na Rest.li. Strona o protokole mówi wprost, jak wygląda ustawienie domyślne: "To use version 2.0, you must pass X-Restli-Protocol-Version: 2.0.0 as the header in your API requests. If you don't pass a header, your call will default to version 1.0."

Powrót do wersji 1.0 nie wywołuje błędu. Zmienia składnię oczekiwaną przez serwer, co jest gorsze:

Co robiszProtokół 1.0Protokół 2.0
Pobieranie zbiorcze po id?ids=1&ids=2&ids=3?ids=List(1,2,3)
Klucz zasobu z URNNiezakodowany urn:li:...urn%3Ali%3A... z ( jako %28
Parametr listyparam.aList[0]=foo&param.aList[1]=barparam=(aList:List(foo,bar,baz))

Żądanie bez nagłówka protokołu jest więc analizowane według reguł, pod które twój klient nie pisze, a wynikające z tego błędy wskazują na parametry, a nie na brakujący nagłówek. LinkedIn zaznacza też, że "plans to deprecate protocol version 1.0 in the near future", nie podając daty. Wysyłaj 2.0.0 przy każdym wywołaniu, a problem w ogóle się nie pojawi.

Które endpointy LinkedIna wymagają nagłówka wersji?

Te pod /rest/. Starsze endpointy /v2/ go nie przyjmują i ten podział wyjaśnia większość nieporozumień w integracjach sprzed 2022 roku.

Ścieżka bazowaLinkedin-VersionX-Restli-Protocol-Version
https://api.linkedin.com/rest/WymaganyWymagany, 2.0.0
https://api.linkedin.com/v2/NieudokumentowanyWymagany, 2.0.0

Przewodnik Share on LinkedIn dla aplikacji konsumenckich, który nadal opisuje POST https://api.linkedin.com/v2/ugcPosts i POST https://api.linkedin.com/v2/assets?action=registerUpload, wymienia dokładnie jeden wymagany nagłówek: "All requests require the following header: X-Restli-Protocol-Version: 2.0.0." Nagłówek wersji w ogóle się tam nie pojawia.

Każde wersjonowane wywołanie dotyczące obrazów i postów potrzebuje obu, dlatego nagłówek występuje w każdym przykładowym żądaniu w omówieniu tego, jak initializeUpload zamienia plik w URN obrazu, a wiersze schematu opisujące limity, takie jak górna granica 4 086 znaków tekstu alternatywnego, znajdują się na wersjonowanych stronach zmieniających się z miesiąca na miesiąc. Jeśli odczytujesz limit z wersji, której nie wysyłasz, czytasz niewłaściwy kontrakt.

Najczęściej zadawane pytania

Programista przy biurku z dwoma monitorami, czyli miejsce, w którym sprawdza się wartość nagłówka w dokumentacji przed wysłaniem żądania.

Jaki jest poprawny format nagłówka LinkedIn-Version?

Sześć cyfr w formacie YYYYMM, np. Linkedin-Version: 202608. LinkedIn opisuje tę wartość jako odpowiadającą "to the documentation version you are referencing", więc wartość nagłówka i czytana strona dokumentacji powinny wskazywać ten sam miesiąc.

Jaki błąd zwraca LinkedIn, gdy brakuje nagłówka wersji?

400 z kodem VERSION_MISSING i komunikatem "A version must be present. Please specify a version by adding the Linkedin-Version header." Sprawdzenie odbywa się przed analizą treści żądania.

Czym jest HTTP 426 NONEXISTENT_VERSION w API LinkedIna?

To odpowiedź na wersję, która została wycofana. Udokumentowana treść to {"status": 426, "code": "NONEXISTENT_VERSION", "message": "Requested version yyyymmdd is not active"}, a 426 oznacza status Upgrade Required, czyli tutaj konieczność zaktualizowania wartości nagłówka.

Jak często LinkedIn wydaje nową wersję API?

Co miesiąc. LinkedIn publikuje nową wersję każdego miesiąca i wspiera każdą "for a minimum of one (1) year", a dla każdej wersji udostępnia listę zmian w zasobach.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Czy potrzebne są oba nagłówki, LinkedIn-Version i X-Restli-Protocol-Version?

Tak, w endpointach /rest/. Posts API podaje, że wszystkie API wymagają Linkedin-Version w formacie YYYYMM oraz X-Restli-Protocol-Version: 2.0.0, a żądanie bez tego drugiego po cichu wraca do protokołu 1.0 z jego inną składnią zapytań.

Jak zapisuje się nagłówek: LinkedIn-Version czy Linkedin-Version?

Dokumentacja LinkedIna wszędzie używa Linkedin-Version, również w komunikacie o błędzie. Nazwy pól HTTP nie rozróżniają wielkości liter, więc każda pisownia dotrze do serwera, ale tylko ta z dokumentacji zostanie znaleziona podczas przeszukiwania stron LinkedIna.

Czy nagłówek LinkedIn-Version działa ze starszymi endpointami v2?

Nie, ten wymóg dotyczy konkretnej ścieżki bazowej. Linkedin-Version odnosi się do wywołań pod https://api.linkedin.com/rest/, czyli ścieżki wprowadzonej przez LinkedIna w czerwcu 2022 roku. Starsze endpointy pod https://api.linkedin.com/v2/, takie jak POST /v2/ugcPosts, w ogóle nie dokumentują tego nagłówka, tylko X-Restli-Protocol-Version.

Czy LinkedIn może zmienić zachowanie wersji po jej wydaniu?

Może, ale w określonych granicach. Zastrzega sobie prawo do wydania poprawki do wersji w razie krytycznych problemów z bezpieczeństwem, prywatnością lub błędami, choć określa prawdopodobieństwo jako minimalne. Roczny okres wsparcia gwarantuje, że wersja pozostanie dostępna, a nie że jej zachowanie przez ten rok się nie zmieni.

Co zmieniło się w API LinkedIna w czerwcu 2022 roku?

Marketing APIs LinkedIna doczekały się wtedy pierwszego wersjonowanego wydania pod nową ścieżką bazową https://api.linkedin.com/rest/. Wszystko, co nadal korzysta ze starszej ścieżki https://api.linkedin.com/v2/, powstało przed tą zmianą, podlega innym zasadom i w ogóle pomija nagłówek Linkedin-Version.

Dlaczego działająca integracja z LinkedInem może nagle przestać działać z dnia na dzień?

Najczęstszą cichą przyczyną jest wycofana wersja w nagłówku. W kodzie nic się nie zmienia, ale gdy kończy się roczny okres wsparcia wersji, każde wywołanie, które ją wskazuje, zaczyna zwracać 426 NONEXISTENT_VERSION zamiast poprawnej odpowiedzi. Szczególnie narażone są zaplanowane publikacje, bo nagłówek często ustawia się raz i nigdy do niego nie wraca.

Czy ten artykuł był pomocny?

Chętnie poznamy opinię!

Więcej naszych treści w Google

Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.

Jeszcze chwila...

AdaptlyPost

AdaptlyPost

Planowanie treści na wszystkich platformach

Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Powiązane hasła ze słownika

Powiązane artykuły