Controllo delle versioni dell'API per il servizio DICOM

Questa guida di riferimento offre una panoramica dei criteri di versione dell'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

Le route senza una versione non sono supportate.

Versioni supportate

Attualmente le versioni supportate sono:

• Versione preliminare v1.0
• v1
• v2

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

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

Dichiarazione di conformità DICOM

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

• Istruzione di conformità DICOM v1
• Istruzione di conformità DICOM v2

Versioni non definitive

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

Come vengono incrementate le versioni

Attualmente viene incrementata solo la versione principale ogni volta che viene apportata un'interruzione, che viene considerata non compatibile con le versioni precedenti.

Ecco 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. È possibile 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 interruzione (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 il sistema restituisce le intestazioni api-supported-versions e api-deprecated-versions quando appropriato.

• Api-supported-versions elenca le versioni supportate per l'API richiesta. Viene restituito solo quando si chiama un endpoint annotato con ApiVersion("<someVersion>").

• api-deprecated-versions elenca 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)]