Obsługa wersji interfejsu API dla usługi DICOM
Ten przewodnik referencyjny zawiera omówienie zasad wersji interfejsu API dla usługi DICOM.
Określanie wersji interfejsu API REST w żądaniach
Wersja interfejsu API REST musi być jawnie określona w adresie URL żądania, tak jak w poniższym przykładzie:
<service_url>/v<version>/studies
Uwaga
Trasy bez wersji nie są obsługiwane.
Obsługiwane wersje
Obecnie obsługiwane wersje to:
- Wersja wstępna w wersji 1.0
- v1
- v2
Dokument OpenAPI dla obsługiwanych wersji można znaleźć pod następującym adresem URL:
<service_url>/v<version>/api.yaml
Instrukcja zgodności z programem DICOM
Wszystkie wersje interfejsów API DICOM będą zawsze zgodne ze specyfikacjami DICOMweb™ Standard, ale różne wersje mogą uwidaczniać różne interfejsy API. Aby uzyskać szczegółowe informacje, zobacz określoną wersję instrukcji zgodności:
Wersje wstępne
Wersja interfejsu API z etykietą "wersja wstępna" wskazuje, że wersja nie jest gotowa do produkcji i powinna być używana tylko w środowiskach testowych. Te punkty końcowe mogą napotkać zmiany powodujące niezgodność bez powiadomienia.
Jak są zwiększane wersje
Obecnie zwiększamy tylko wersję główną, gdy wystąpi zmiana powodująca niezgodność, która jest uważana za niezgodną z poprzednimi wersjami.
Poniżej przedstawiono kilka przykładów zmian powodujących niezgodność (wersja główna jest zwiększana):
- Zmiana nazwy lub usuwanie punktów końcowych.
- Usuwanie parametrów lub dodawanie obowiązkowych parametrów.
- Zmiana kodu stanu.
- Usunięcie właściwości w odpowiedzi lub zmianę typu odpowiedzi w ogóle, ale jest w porządku, aby dodać właściwości do odpowiedzi.
- Zmiana typu właściwości.
- Zachowanie, gdy interfejs API zmieni się, na przykład zmiany w logice biznesowej używanej do wykonania operacji foo, ale teraz działa na pasku.
Zmiany powodujące niezgodność (wersja nie jest zwiększana):
- Dodanie właściwości, które są dopuszczające wartość null lub mają wartość domyślną.
- Dodawanie właściwości do modelu odpowiedzi.
- Zmiana kolejności właściwości.
Nagłówek w odpowiedzi
Funkcja ReportApiVersions jest włączona, co oznacza, że w razie potrzeby zwrócimy nagłówki api-supported-versions i api-przestarzałe wersje.
Wersje obsługiwane przez interfejs API zawierają listę wersji obsługiwanych przez żądany interfejs API. Jest zwracany tylko podczas wywoływania punktu końcowego oznaczonego adnotacją za pomocą polecenia
ApiVersion("<someVersion>").Wersje przestarzałe interfejsu API będą zawierać listę wersji przestarzałych dla żądanego interfejsu API. Jest zwracany tylko podczas wywoływania punktu końcowego oznaczonego adnotacją za pomocą polecenia
ApiVersion("<someVersion>", Deprecated = true).
Przykład:
[ApiVersion("1")]
[ApiVersion("1.0-prerelease", Deprecated = true)]
Następne kroki
W tym artykule przedstawiono zasady wersji interfejsu API dla usługi DICOM. Aby uzyskać więcej informacji na temat usługi DICOM, zobacz