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

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ć.

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ć.

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.

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.

1. 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.
2. 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ę.

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

Polecenie cmdlet programu PowerShellInvoke-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ć.

Zauważyłem dwie konsekwencje:

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