Controllo delle versioni dell'API per il servizio DICOM
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