Jeśli uruchomię interfejs API, jeśli poprawię nagłówek typu treści, czy to nie psuje klientów?

14

Prowadzimy interfejs API, z którego korzysta wiele osób. Z powodu pewnej starszej niezręczności z mojej strony, jednym z punktów końcowych jest zwracanie niewłaściwego nagłówka typu zawartości , jskiedy powinien json. Moje pytanie brzmi: jeśli naprawimy to, zamieniając, aby zwrócić prawidłową wartość, w jakim stopniu mogłoby to zepsuć naszych obecnych klientów? Innymi słowy, czy spodziewałbyś się, że wiele różnych bibliotek klienta HTTP zgłasza krytyczne błędy, widząc taką zmianę?

Staramy się zdecydować, czy jest to zmiana, którą możemy wprowadzić bez nadmiernego pocenia się, czy też powinniśmy uważnie wysłać wiadomość e-mail do wszystkich użytkowników i ogłosić wieloletni okres amortyzacji ... lub coś pomiędzy.

Prawdopodobnie zależy to nieco od rodzaju różnych klientów HTTP, więc przyjrzałem się agentom użytkownika. Odpowiedź: wiele różnych! Oto niektóre z najlepszych:

„okhttp / 3.2.0”, „zapytania python / 2.10.0”, „Ruby”, „pytania python / 2.7.0”, „Mozilla / 5.0”, „Java / 1.8.0_91”, „pytania python /2.4.3 ”,„ okhttp / 3.3.0 ”,„ Lucee ”,„ Dalvik / 2.1.0 ”,„ Google-HTTP-Java-Client / 1.21.0 ”,„ PHP_appname ”,„ NativeHost ”,„ Java /1.7.0_67 ”,„ Apache-HttpClient / UNAVAILABLE ”,„ Dalvik / 1.6.0 ”,„ Web-sniffer / 1.1.0 ”,„ unirest-objc / 1.1 ”

Różne różne biblioteki języków mobilnych i serwerów. Przeważnie nie przeglądarki obsługujące javascript, ale niektóre też.

Wydaje się, że większość ludzi nie zauważa, że typ zawartości jest nieprawidłowy, ale co jakiś czas pojawia się nowe żądanie pomocy technicznej narzekające na ten problem, dlatego chcielibyśmy to naprawić.

http http-headers

— Harry Wood
źródło

4

Zakładam, że klienci, którzy działają poprawnie z niepoprawnym nagłówkiem typu zawartości, nie przestaną działać po ustawieniu poprawnego, ale wiesz, co mówią o założeniach. Przetestuj, z wyprzedzeniem przekaż swoje zmiany do bazy użytkowników i / lub wbuduj jakąś dodatkową logikę, że jeśli jakiś klient się zepsuje, możesz go wykryć i nadal zwracać niepoprawny nagłówek typu zawartości (lub odwrotnie, zwróć odpowiedni dla tych klientów, którzy generują zgłoszenia do pomocy technicznej i zachowują to samo dla obecnych użytkowników / agentów użytkowników).

— HBruijn,

5

obowiązkowe xkcd: xkcd.com/1172

— njzk2

Nie masz wersji interfejsu API?

— Michael Hampton

Mamy tylko główny numer wersji dla całego interfejsu API, który spodziewalibyśmy się za kilka lat, gdy dokonamy dość poważnych zmian. W tym momencie oczywiście naprawilibyśmy ten problem, ale ... wydaje się, że nigdy tego nie zrobimy. To jeden z tych numerów wersji.

— Harry Wood,

30

jak bardzo mogłoby to zepsuć naszych obecnych klientów?

Może całkowicie zatopić ich pancerniki, jeśli napisały kod, który opiera się na tym, że ten typ zawartości jest nieprawidłowy.

Nie spodziewałbym się, że biblioteki będą zgłaszać błędy, ale spodziewam się, że w niektórych przypadkach w przypadku bibliotek ścisłych ich zachowanie zostało zastąpione w celu obsługi nieprawidłowego typu MIME.

Jeśli interfejs API ma gdzieś w polu żądania wartość wersji / wersji, podnieś ją, a w nowej wersji zwróć prawidłowy typ, ale nadal zwracaj niepoprawny typ w starszych wersjach. Jeśli nie masz takiego pola żądania, teraz jest dobry moment, aby je dodać.

— alzee
źródło

6

+1 już za dobrą hiperbolę

— HBruijn

4

Często nie masz wyboru. Klienci, którzy otrzymali ultimatum „zaktualizuj lub odejdź”, mogą zdecydować o tym drugim, co do zasady dobre, a złe w praktyce. Starą wersję można z czasem wycofać.

— alzee,

3

+1 lub wersjonowanie żądań, choć możesz chcieć sprawdzić en.wikipedia.org/wiki/Software_versioning w celu uzyskania dalszych informacji.

— SBoss,

7

@WinstonEwert: Oczywiście, że warto. Ludzie określają, której wersji interfejsu API chcą używać, a następnie ich program nie spontanicznie się pali w czasie między aktualizacją interfejsu API a aktualizacją programu. Jeśli tego nie zrobisz, automatycznie zmieniasz każdą bieżącą i historyczną wersję kodu klienta po zmianie interfejsu. I to jest straszny sposób na uruchomienie usługi.

— Lekkość ściga się z Moniką

1

Nawiasem mówiąc, wydaje się to bardzo dobrym punktem: „Spodziewam się, że w niektórych przypadkach w bibliotekach ścisłych nadpisano ich zachowanie w celu obsługi niepoprawnego typu mime”. Moje przeczucie (w odpowiedzi na całe pytanie) jest takie, że zdecydowana większość klientów biblioteki będą w tym dobrze, ale jest to problem. Niektórzy klienci mogli aktywnie obejść ten problem, a zamiana go przerwie. Zastanawiam się, ile to się wydarzyło.

— Harry Wood,

11

Czy spodziewałbyś się, że wiele różnych bibliotek klienta HTTP zgłasza krytyczne błędy, widząc taką zmianę?

Nie. Każda biblioteka klienta HTTP, którą znam, zignoruje nagłówek typu zawartości, chyba że programista konkretnie przeczyta ten nagłówek i coś z nim zrobi. Mogę sobie wyobrazić bibliotekę, w której typ zawartości: aplikacja / json automatycznie powoduje zaangażowanie parsera json, ale nie znam żadnego przypadku, w którym tak się dzieje.

Wydaje się, że większość ludzi nie zauważa, że typ zawartości jest nieprawidłowy, ale co jakiś czas pojawia się nowe żądanie pomocy technicznej narzekające na ten problem, dlatego chcielibyśmy to naprawić.

Jak zauważyli nieprawidłowy nagłówek? Może warto na to spojrzeć, ponieważ jeśli nieprawidłowy nagłówek faktycznie powodował problemy, najwyraźniej nie ignorowali go i mogą mieć problemy, jeśli zostanie to naprawione.

— Winston Ewert
źródło

Moja odpowiedź zawiera przykład, w którym tak naprawdę by się to wydarzyło .

— briantist

Jeśli użyjesz jQuery $.ajaxi nie określisz tej dataType:opcji, ustali on typ odpowiedzi z Content-typenagłówka. Jeśli tak application/json, automatycznie go przeanalizuje przed przekazaniem go do osoby dzwoniącej.

— Barmar,

6

Zbyt trudno powiedzieć bez wypisania się od wszystkich klientów. Sugeruję skorzystanie z jednego z dwóch poniższych sposobów uaktualnienia interfejsu API do wersji v.Next.

Rozszerz istniejące API. Dodaj ciąg zapytania lub inną zmienną do swojego interfejsu API, która oznacza użycie v.Next. Dla wszystkich żądań używających tej zmiennej użyj zaktualizowanego typu zawartości.
Uruchom instancję pomostową lub przedprodukcyjną interfejsu API równolegle z bieżącym interfejsem API. Powinien być prawie identyczny z produkcją. Nawet przy użyciu tego samego zaplecza. Chociaż ten będzie miał proponowane zmiany dla v.Next.

W obu przypadkach poinformuj klientów o zmianach, które chcesz wprowadzić, oraz o docelowej dacie / godzinie zmiany. Zachęć ich do przetestowania na długo przed datą docelową, aby upewnić się, że nie wystąpią zakłócenia usługi.

Upewnij się, że masz dedykowaną stronę opisującą zmiany wprowadzone w v.Next. Powinno to zostać uwzględnione w korespondencji wysyłanej do klientów. Jeśli omawiałeś jakieś poprawki z istniejącymi klientami, dołącz je na tej stronie.

Wreszcie, stąp na linii między nadmierną komunikacją z klientami a spamowaniem ich. Powiadomienia te można łatwo przeoczyć, gdy pojawiają się bardziej bezpośrednie / pilne priorytety.

FWIW, jeśli teraz coś działa, nie martwiłbym się tym zbytnio. Jeśli na przykład okaże się, że powoduje to znaczną lukę w zabezpieczeniach, byłby to świetny powód do wypchnięcia tej zmiany. W przeciwnym razie czekałbym na coś bardziej palącego, aby dołączyć tę zmianę.

— użytkownik2320464
źródło

Dzięki. To nie jest odpowiedź, którą chciałem usłyszeć, ale może masz rację. Po prostu musimy wprowadzić zmianę bardzo ostrożnie. Czy jest to jednak „zbyt trudne do powiedzenia”? Wydaje mi się, że miałem nadzieję, że niektórzy ludzie doświadczą prawdopodobnego wpływu tego rodzaju zmiany nagłówka typu treści (pomijając bardziej ogólne uwagi na temat wersjonowania)

— Harry Wood

5

Oto przykład biblioteki (cóż, pojedynczego polecenia), która by się zepsuła:

Polecenie cmdlet programu PowerShell Invoke-RestMethod działa inaczej z JSON. Jeśli wynikiem żądania jest JSON, XML lub ATOM / RSS (i myślę, że jest oparty na nagłówku), analizuje / deserializuje je i zwraca obiekty rodzime, w przeciwnym razie zwraca surowe dane.

Tak więc istniejący kod zostałby napisany, aby poradzić sobie z łańcuchem (być może przez przekazanie go ConvertFrom-Json) i nagle zacząłby się zawodzić.

— briantist
źródło

blogs.technet.microsoft.com/heyscriptingguy/2013/10/21/... potwierdza teorię, że wygląda to na nagłówek.

— Winston Ewert,

-2

Zauważyłem dwie konsekwencje:

Niektóre biblioteki klienta nie przetwarzają poprawnie odpowiedzi. Na przykład odpowiedź zwraca ciąg zamiast json lub tablicy.
Kompresja nie zawsze jest stosowana.

— użytkownik368565
źródło

Z pewnością to ten, który wysyła dane, a nie ten, który stosuje kompresję?

— TRiG,