Oferuję małym klientom Web Services API, który zamierzam rozwijać w miarę upływu czasu. Potrzebuję jakiejś wersji, ale nie mogę znaleźć żadnych informacji o tym, jak robisz coś takiego.Web Services API Versioning
Czy istnieje najlepsza praktyka?
Jak mogę dodawać nowe funkcje bez naruszania zgodności z usługami internetowymi?
Dodaj "numer wersji interfejsu API" jako parametr we wszystkich swoich interfejsach API, a następnie zaimplementuj wzorzec strategii w kodzie usługi sieci Web, gdzie numer wersji określa, jakiej strategii użyć.
Generalnie dodawam ciąg wersji do adresu URL usługi sieci Web, podając "wersjonowane punkty końcowe". Kod implementujący te punkty końcowe może być współdzielony, jeśli różnice są trywialne i mogą być obsługiwane za pomocą tego samego kodu, lub kod można sklonować lub gdzieś pomiędzy.
Różne wersjonowane punkty końcowe mogą również używać wersjonowanych schematów XML, jeśli tego właśnie potrzebujesz.
Wersjonowanie to skomplikowany temat, dlatego po pierwsze trzeba zdefiniować cele w bardziej opisowy sposób. Byłoby wspaniale powiedzieć, że masz interfejs zapewniający, że nigdy nie złamiesz kompatybilności, ale w zależności od nowej funkcjonalności może to nie być nawet możliwe. Istnieją różne sytuacje i różne kompromisy.
Jeśli Twoim zamiarem jest dostarczanie nowych funkcji tylko nowym konsumentom, a wszyscy Twoi konsumenci są bezpośrednimi konsumentami (bez pośredników, struktur itp.), Najlepszym rozwiązaniem jest podejście dyskretne. Za każdym razem, gdy dodajesz funkcję, która grozi uszkodzeniem, utwórz nowy punkt końcowy, nadaj mu nowy numer wersji, a następnie poinformuj konsumentów, aby potwierdzili i zmień konfiguracje. Strategia ta jest całkiem wypróbowana i prawdziwa, ale ma wady polegające na obciążaniu konsumentów obowiązkiem aktualizacji. Ponadto, jeśli istnieją zależności między usługami, może to być trudne do śledzenia. Plusem jest to, że jeśli kod się zepsuje, to nie jest (bezpośrednio) twoja wina.
Inną główną strategią jest interfejs rozszerzalny. Są trzy różne odmiany, o których wiem. Po pierwsze, jest to typ interfejsu, który stara się tak dobrze opisać domenę usług, że każda możliwa funkcja, którą można dodać, jest w jakiś sposób możliwa z uwagi na istniejący interfejs. Jeśli to brzmi trudno, to jest. Można to nazwać doskonałym interfejsem. Wszystko jest całkowicie opisane, ale cała domena jest również całkowicie opisana. "Doskonały" jest naprawdę tylko na papierze.
Druga odmiana to typ, który wygląda jak normalny interfejs, ale dodaj ogólne punkty rozszerzenia. W WSDL oznacza to xs: dowolne, pary nazwa-wartość lub coś podobnego. Można to nazwać podstawowym rozszerzalnym interfejsem. Nie jest to trudne, ale nie bez jego komplikacji. Punkty rozszerzenia mogą utrudniać pracę interfejsu w niektórych narzędziach (xs: any) lub jawnie tracą zdolność sprawdzania poprawności danych wejściowych i wyjściowych (pary nazwa-wartość). Łatwo też nadużywać tych punktów rozszerzeń w sposób, który sprawia, że wersja 3 lub 4 jest dość trudna w użyciu.
Trzecia odmiana to typ, który konwertuje interfejs na strumień bajtowy. Możesz nazwać te bogate interfejsy. Nie są bez uzasadnienia, ale jeśli używasz jednego, możesz zapytać, dlaczego w ogóle korzystasz z usług internetowych. Może powinieneś pomyśleć o surowym TCP/IP lub podstawowym HTTP GET/POST. Ale może masz dość skomplikowanych WSDL i XSD i chcesz zacząć od zera, ale jesteś związany z usługami sieciowymi z jakiegoś powodu infrastrukturalnego. Zdaj sobie jednak sprawę, że po uruchomieniu tej ścieżki będziesz potrzebować zupełnie nowego sposobu opisywania swoim klientom, jak/nie korzystać z Twojej usługi, i jeśli używasz XSD do tego ... dobrze jesteś z powrotem tam, gdzie ty zacząłeś.
Najlepiej jest poznać wszystkie te opcje i podejść do projektu usługi, próbując najpierw "perfekcyjnego interfejsu", a następnie rezygnując i dodając ogólne punkty rozszerzalności. Próba zaprojektowania idealnego interfejsu zmusi cię do nauki rzeczy, które poprawią twoją usługę, nie tylko twojego interfejsu, ale zajmie to trochę czasu, a jeśli nie ograniczysz tego czasu, to potrwa to na zawsze.
Niewielki interfejs z prawdziwym bogiem zawiera interfejs opakowania. Jeśli system ma warstwy, chcesz, aby interfejs również był w warstwach. Gdy zmieniasz warstwę B, chcesz zmienić tylko warstwę B, a nie wszystkie wystąpienia w warstwie C.
wszystkie trochę abstrakcyjne i ciasto na niebie dla mojego upodobania. –
Jak dokładnie powinien on być najbardziej szczegółowy, biorąc pod uwagę informacje zawarte w pytaniu oryginalnym? – HDave
Jedną z możliwości jest zaprojektowanie wszystkich operacji usługi sieciowej tak, aby miały tylko jeden parametr typu dziedziczącego po abstrakcji. typ zawierający numer wersji. To podejście jest realizowane przez eBay web services platform. Coś następującym:
<xsd:complexType name="AbstractRequestType">
<xsd:attribute name="version" type="string" />
....
<xsd:complexType name="AddCustomerRequestType">
<xsd:complexContent>
<xsd:extension base="AbstractRequestType">
....
then use AddCustomerRequestType as a type of only parameter
in addCustomer web service operation.
Dodatkowo, jeśli pracujesz nad http może wymagać, aby dodać wersję jako parametr HTTP GET do usług internetowych końcowego URL, dzięki czemu będziemy w stanie wykryć wersję żądany łatwo http://server/service?version=1
najczęstszą strategią że widziałem to na wersji WSDL dodając o wersjach identyfikację (zwykle yyyy/MM[/dd]) do nazw obiektów w WSDL, a mianowicie:
targetNamespace="http://schemas.mycompany.com/2010/01/widgets"
Można to zrobić na poziomie: type (types/schema) lub na całym poziomie WSDL - <definitions> w wersji 1.1 lub <description> w wersji 2.0.
trochę przestarzałe, ale this link IBM Developer Works zapewnia uzasadnienie dla takiego podejścia, a szczególnie gdy muszą być zwiększane wersje:
wstecz wersja kompatybilna/non-breaking zmiany:
Przełamując zmiany:
ta będzie działać tylko wtedy, gdy wersjonowane usług internetowych podejmują * dokładnie * The te same argumenty, więc obowiązuje ten sam WSDL. Jeśli w nowej wersji wymaga dodania nowego atrybutu, co robisz? –