Schema powiedziała tak, serwer powiedział nie

Ciao! 🇵🇱🇮🇹

29 lipca chciałem wysłać dziewięć zdjęć jako jedną karuzelę, i schemat API przysiągł mi, że to formalność.

Skłamał, choć technicznie nie powiedział ani słowa nieprawdy.

Lecimy z tematem 🚀

Enum, który kłamał

Chciałem wysłać dziewięć zdjęć z folderu jako jedną karuzelę do przesuwania, na Facebooku i Instagramie, w automatyzacji dla Akademii Negocjacji. Bez tego funkcja wysyłałaby dziewięć osobnych postów zamiast jednego, co dla klienta wyglądałoby jak spam na feedzie.

Kilka tygodni wcześniej, przy innej funkcji tego samego projektu, sprawdziłem przez introspekcję Buffer API jakie typy postów obsługuje Instagram. Odpowiedź z serwera wprost wymieniała carousel obok post, story i reel. Logiczny wniosek: skoro schema formalnie dopuszcza tę wartość, wystarczy ją wpisać w metadata.instagram.type i sprawa załatwiona, bez dalszego zgadywania.

Etap 1: schema mówi tak

Enum PostType dla Instagrama zawierał dziewięć wartości, w tym carousel, potwierdzone wcześniejszą introspekcją co do joty. Napisałem zapytanie z type: "carousel" i dziewięcioma zdjęciami w liście assets, przekonany, że to tylko formalność, skoro sam producent API formalnie potwierdził tę wartość w swoim schemacie.

Etap 2: serwer mówi nie

Buffer odpowiedział jasnym błędem: „Invalid post: Instagram does not support the ‘carousel’ post type. Valid types are post, story, or reel”. Ten sam typ, który enum w schemacie oficjalnie dopuszczał, walidacja biznesowa po stronie serwera odrzuciła bez wahania.

Etap 3: rozwiązanie było prostsze niż problem

Karuzela w Bufferze to zwykły type: "post" z kilkoma zdjęciami w assets. Bez żadnego specjalnego typu posta. Buffer sam renderuje karuzelę na podstawie liczby przesłanych obrazków, identycznie dla Facebooka, który w swoim enumie w ogóle nie ma wartości carousel. Przetestowałem to z flagą saveToDraft: true, więc nic się nie opublikowało, i sprawdziłem przez zapytanie zwrotne, że wszystkie dziewięć zdjęć trafiło w podanej kolejności. Buffer w swoim centrum pomocy potwierdza ten sam limit wprost: do dziesięciu zdjęć w karuzeli na Instagramie i Facebooku. LinkedIn ma podobny mechanizm z limitem dziewięciu zdjęć, ale w tym projekcie karuzelę na LinkedIn robimy przez osobny dokument PDF, nie przez listę obrazków.

Schemat GraphQL opisuje tylko możliwy kształt danych, nie logikę biznesową, która je akceptuje albo odrzuca. Enum może formalnie dopuszczać wartość, której backend nigdy nie przyjmie.

🛠️ Narzędzie

Introspekcja GraphQL (__schema/__type)

To zapytanie wbudowane w każde API GraphQL, które pyta serwer wprost, jakie typy, pola i wartości enumów naprawdę obsługuje, bez zgadywania z dokumentacji. Używam go za każdym razem przed dopisaniem nowej funkcji do automatyzacji Buffera dla Akademii Negocjacji, na przykład żeby sprawdzić, czy TikTok albo YouTube w ogóle mają pole rozróżniające post od reela. Polecam, bo dokumentacja bywa nieaktualna, a zapytanie { __schema { mutationType { fields { name } } } } zawsze pokazuje stan faktyczny.

GraphQL introspection, dokumentacja oficjalna

🌍 Ze świata

• OpenAI reportedly finds evidence that more of its agents ran amok. Kolejny dowód, że pewność siebie modelu i poprawność jego działania to dwie zupełnie różne rzeczy.

• When Your API Documentation Lies: Building an AI-Powered Validator to Catch the Drift. To dokładnie to, co spotkało mnie z enumem Buffera, tylko ktoś zbudował na tym cały produkt do wykrywania rozjazdu między dokumentacją a rzeczywistością.

• Ars Technica Pulls Article With AI Fabricated Quotes About AI Generated Article. Redakcja od lat ostrzegająca przed nadmiernym poleganiem na AI dała się złapać dokładnie na tym, przed czym ostrzegała.

😄 Na koniec

Poprosiłem GraphQL o karuzelę zdjęć. Dostałem karuzelę błędów.

Jeśli ktoś w Twoim otoczeniu powinien to przeczytać, prześlij mu ten numer. To najlepsza forma wsparcia.