Funcionalidades de la API REST de FHIR para Azure API for FHIR
En este artículo, trataremos algunos de los matices de las interacciones RESTful de Azure API for FHIR.
Creación o actualización condicional
Azure API for FHIR admite la creación, la creación condicional, la actualización y la actualización condicional, tal y como se define en la especificación de FHIR. Un encabezado útil en estos escenarios es el encabezado If-Match . El If-Match encabezado se usa y validará la versión que se va a actualizar antes de realizar la actualización. ETag Si no coincide con el esperadoETag, generará el mensaje de error 412 Error de condición previa.
Eliminación y eliminación condicional
Azure API for FHIR ofrece dos tipos de eliminación. Hay Delete, que también se conoce como Hard + Soft Delete y Conditional Delete.
Eliminar (eliminación temporal y dura)
La eliminación definida por la especificación FHIR requiere que después de eliminar un recurso, las lecturas posteriores no específicas de la versión de un recurso devuelven un código de estado HTTP 410. Por lo tanto, el recurso ya no se encuentra a través de la búsqueda. Además, Azure API for FHIR permite eliminar completamente (incluido todo el historial) del recurso. Para eliminar completamente el recurso, puede pasar una configuración hardDelete de parámetro a true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Si no pasa este parámetro o se establece hardDelete en false, las versiones históricas del recurso seguirán estando disponibles.
Nota:
Si solo desea eliminar el historial, Azure API for FHIR admite una operación personalizada denominada $purge-history. Esta operación permite eliminar el historial de un recurso.
Eliminación condicional
La eliminación condicional permite pasar criterios de búsqueda para eliminar un recurso. De forma predeterminada, la eliminación condicional permite eliminar un elemento a la vez. También puede especificar el _count parámetro para eliminar hasta 100 elementos a la vez. A continuación se muestran algunos ejemplos de uso de la eliminación condicional.
Para eliminar un solo elemento mediante la eliminación condicional, debe especificar criterios de búsqueda que devuelvan un solo elemento.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Puede realizar la misma búsqueda, pero incluir hardDelete=true para eliminar también todo el historial.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Para eliminar varios recursos, incluya el _count=100 parámetro . Este parámetro eliminará hasta 100 recursos que coincidan con los criterios de búsqueda.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Recuperación de archivos eliminados
Si no usa el parámetro de eliminación permanente, los registros de Azure API for FHIR seguirán existiendo. Los registros se pueden encontrar realizando una búsqueda de historial en el recurso y buscando la última versión con datos.
Si se conoce el identificador del recurso que se eliminó, use el siguiente patrón de dirección URL:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Por ejemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Si no se conoce el identificador del recurso, realice una búsqueda del historial en todo el tipo de recurso:
<FHIR_URL>/<resource-type>/_history
Por ejemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Después de encontrar el registro que desea restaurar, use la PUT operación para volver a crear el recurso con el mismo identificador o use la POST operación para crear un nuevo recurso con la misma información.
Nota:
No hay ninguna expiración basada en el tiempo para los datos de historial o eliminación temporal. La única manera de quitar el historial o los datos eliminados temporalmente es con una eliminación permanente o la operación del historial de purga.
Revisión y revisión condicional
Patch es una valiosa operación RESTful cuando necesita actualizar solo una parte del recurso de FHIR. El uso de patch permite especificar los elementos que desea actualizar en el recurso sin tener que actualizar todo el registro. FHIR define tres maneras de aplicar revisiones a los recursos: revisión JSON, revisión XML y revisión de FHIRPath. El servicio FHIR admite la revisión JSON y la revisión de FHIRPath junto con la revisión JSON condicional y la revisión FHIRPath condicional (que permite aplicar revisiones a un recurso basado en criterios de búsqueda en lugar de un identificador de recurso). Para ver algunos ejemplos, consulte el archivo REST de revisión de FHIRPath de ejemplo y el archivo REST de revisión JSON para cada enfoque. Para obtener más información, lea la documentación de HL7 para las operaciones de revisión con FHIR.
Nota:
Al usar PATCH en STU3 y, si solicita una agrupación de historial, el recurso Bundle.entry.request.method revisado se asigna a PUT. Esto se debe a que STU3 no contiene una definición para el PATCH verbo en el conjunto de valores HTTPVerb.
Revisión con revisión de FHIRPath
Este método de revisión es el más eficaz, ya que aprovecha FHIRPath para seleccionar el elemento de destino. Un escenario común es usar FHIRPath Patch para actualizar un elemento de una lista sin conocer el orden de la lista. Por ejemplo, si desea eliminar la información de telecomunicaciones domésticas de un paciente sin conocer el índice, puede usar el ejemplo siguiente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de contenido: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Las operaciones de revisión de FHIRPath deben tener establecido el application/fhir+json encabezado Content-Type. FHIRPatch Patch admite operaciones de adición, inserción, eliminación, eliminación y movimiento. Las operaciones de revisión de FHIRPatch también se pueden integrar fácilmente en agrupaciones. Para obtener más ejemplos, consulte el archivo REST de revisión de FHIRPath de ejemplo.
Revisión con revisión JSON
La revisión JSON en el servicio FHIR se ajusta a la especificación bien utilizada definida por el Grupo de tareas de ingeniería de Internet. El formato de carga no usa recursos de FHIR y, en su lugar, usa un documento JSON que aprovecha JSON-Pointers para la selección de elementos. La revisión JSON es más compacta y tiene una operación de prueba que le permite validar que una condición es verdadera antes de realizar la revisión. Por ejemplo, si desea establecer un paciente como fallecido solo si aún no están marcados como fallecidos, puede usar el ejemplo siguiente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de contenido: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Todas las operaciones de revisión json deben tener establecido el application/json-patch+json encabezado Content-Type. Json Patch admite operaciones de adición, eliminación, reemplazo, copia, movimiento y prueba. Para obtener más ejemplos, consulte el archivo REST de revisión JSON de ejemplo.
Revisión json en agrupaciones
De forma predeterminada, la revisión json no se admite en los recursos de agrupación. Esto se debe a que un lote solo admite con recursos de FHIR y la carga de revisiones JSON no es un recurso de FHIR. Para solucionar esto, usaremos recursos binarios con un tipo de contenido de "application/json-patch+json" y la codificación base64 de la carga JSON dentro de un paquete. Para obtener información sobre esta solución alternativa, vea este tema en FHIR Chat Zulip.
En el ejemplo siguiente, queremos cambiar el género del paciente a mujer. Hemos tomado la revisión [{"op":"replace","path":"/gender","value":"female"}] JSON y la hemos codificado en base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Pasos siguientes
En este artículo, ha obtenido información sobre algunas de las funcionalidades REST de Azure API for FHIR. A continuación, puede obtener más información sobre los aspectos clave para buscar recursos en FHIR.
FHIR es una marca registrada de HL7 y se usa con el permiso de HL7.