Controllo delle versioni dell'API per il servizio DICOM

Articolo
04/28/2023

Questa guida di riferimento offre una panoramica dei criteri di versione api per il servizio DICOM.

Specifica della versione dell'API REST nelle richieste

La versione dell'API REST deve essere specificata in modo esplicito nell'URL della richiesta, come nell'esempio seguente:

<service_url>/v<version>/studies

Nota

Le route senza una versione non sono supportate.

Versioni supportate

Attualmente le versioni supportate sono:

versione 1.0-prerelease
v1
v2

La documentazione OpenAPI per le versioni supportate è disponibile nell'URL seguente:

<service_url>/v<version>/api.yaml

Istruzione di conformità DICOM

Tutte le versioni delle API DICOM sono sempre conformi alle specifiche DICOMweb™ Standard, ma le diverse versioni possono esporre API diverse. Per informazioni dettagliate, vedere la versione specifica dell'istruzione di conformità:

Versioni non definitive

Una versione API con l'etichetta "prerelease" indica che la versione non è pronta per l'produzione e deve essere usata solo negli ambienti di test. Questi endpoint possono riscontrare modifiche di rilievo senza preavviso.

Modalità di incremento delle versioni

Attualmente incrementiamo solo la versione principale ogni volta che è presente una modifica di rilievo, considerata non compatibile con le versioni precedenti.

Di seguito sono riportati alcuni esempi di modifiche di rilievo (la versione principale viene incrementata):

Ridenominazione o rimozione di endpoint.
Rimozione di parametri o aggiunta di parametri obbligatori.
Modifica del codice di stato.
Eliminazione di una proprietà in una risposta o modifica di un tipo di risposta, ma è consigliabile aggiungere proprietà alla risposta.
Modifica del tipo di una proprietà.
Comportamento quando un'API cambia, ad esempio le modifiche apportate alla logica di business usata per eseguire il foo, ma ora esegue la barra.

Modifiche non di rilievo (la versione non viene incrementata):

Aggiunta di proprietà che sono nullable o hanno un valore predefinito.
Aggiunta di proprietà a un modello di risposta.
Modifica dell'ordine delle proprietà.

Intestazione in risposta

ReportApiVersions è attivato, il che significa che le intestazioni verranno restituite le intestazioni supportate dalle api e le versioni api-deprecate quando appropriato.

le versioni supportate dall'api elencano quali versioni sono supportate per l'API richiesta. Viene restituito solo quando si chiama un endpoint annotato con ApiVersion("<someVersion>").
le versioni api deprecate elencano le versioni deprecate per l'API richiesta. Viene restituito solo quando si chiama un endpoint annotato con ApiVersion("<someVersion>", Deprecated = true).

Esempio:

[ApiVersion("1")]
[ApiVersion("1.0-prerelease", Deprecated = true)]

Passaggi successivi

In questo articolo sono stati illustrati i criteri di versione dell'API per il servizio DICOM. Per altre informazioni sul servizio DICOM, vedere

Panoramica del servizio DICOM

Condividi tramite