TypeScript Client: REST and conditional API

[GenaRazmakhnin]

Considered Options for Conditional Operations

Our current REST API does not support the use of conditional operations. Here, we are considering the possible options.

import { Patient } from 'aidbox/types'

const resource: Patient = {
  gender: 'male',
  name: [{ given: ['Gena1'], family: 'Razmakhnin1' }],
  identifier: [{ system: 'ACME', value: '001' }],
  resourceType: 'Patient'
}

REST API

await aidbox.resource.create('Patient', resource)

await aidbox.resource.update('Patient', '11c2c2b6-edcb-408e-9705-4d79e741020c', resource)

await aidbox.resource.override('Patient', '11c2c2b6-edcb-408e-9705-4d79e741020c', resource)

await aidbox.resource.delete('Patient', '11c2c2b6-edcb-408e-9705-4d79e741020c')

CONDITIONAL API 1 (rejected)

await aidbox.resource.create('Patient', resource)
  .where('identifier', 'ACME|0001')

await aidbox.resource.update('Patient', resource)
  .where('identifier', 'ACME|0001')

await aidbox.resource.override('Patient', resource)
  .where('identifier', 'system|1')

await aidbox.resource.delete('Patient')
  .where('identifier', 'system|1')

Concerns:

1. For this specific function signature, .where() is required in the conditional update case. However, we can't define the restriction at the type level to use it.
2. There's a conflict in the second argument with basic API; the second argument will be polymorphic. We can use either resource body or iD, which could lead to poor UX.

await aidbox.resource.update('Patient', '11c2c2b6-edcb-408e-9705-4d79e741020c', resource)

await aidbox.resource.update('Patient', resource)
  .where('identifier', 'ACME|0001')

CONDITIONAL API 2 (rejected)

await aidbox.request({
  method: 'PATCH',
  resourceType: 'Patient',
  data: { 
    id: '11c2c2b6-edcb-408e-9705-4d79e741020c',
    name: [{ given: ['Gena'] }]
  },
  search: { identifier: 'ACME|0001'},
  headers: { 'isolation-level': 'read-commit' }
})

Concerns:

1. This approach mixes low-level API with a high-level typed API.
2. We can't provide an ID either inside the data or inside the search. Where should we put the ID? We don't want to concatenate strings, nor do we want to introduce an optional ID parameter.

CONDITIONAL API 3 (rejected)

await aidbox.resource.conditionalCreate('Patient', 'identifier=ACME|0001', resource)

await aidbox.resource.conditionalUpdate('Patient', 'identifier=ACME|0001', resource)

await aidbox.resource.conditionalOverride('Patient', 'identifier=ACME|0001', resource)

await aidbox.resource.conditionalDelete('Patient', 'identifier=ACME|0001')

CONDITIONAL API 4 (current)

await aidbox.resource.conditionalCreate('Patient', resource)
  .where('identifier', 'ACME|0001')

await aidbox.resource.conditionalUpdate('Patient', resource)
  .where('identifier', 'ACME|0001')

await aidbox.resource.conditionalOverride('Patient', resource)
  .where('identifier', 'ACME|0001')

await aidbox.resource.conditionalDelete('Patient')
  .where('identifier', 'ACME|0001')

Here are some further improvement ideas:

const search1: PatientSearchParameters = [[ 'identifier', ['ACME|0001', 'ACME|0002'], 'eq']]
const pt =  new Patient()

const search2 = new Search<Patient>() // new Search('Patient')
search.add('identifier', ['ACME|0001', 'ACME|0002'], 'eq')
search.add('gender', 'female')

await aidbox.resource.conditionalUpdate('Patient', search, resource)

[GenaRazmakhnin]

try {
  const patients = await aidbox.resource.search('Patient')
    .where('name', 'Gena')
    .page(1).count(10).sort('name', 'desc')
    .then(response => { return response })

  console.log(patients)

  const resource: Patient = {
    gender: 'male',
    name: [{ given: ['Gena1'], family: 'Razmakhnin1' }],
    identifier: [{ system: 'Gena', value: '0001' }],
    resourceType: 'Patient'
  }

  const patient = await aidbox.resource.conditionalCreate('Patient', resource)
    .where('identifier', 'ACME|0001')
    .where('organization', 'Organization/acme')
    .where('name', 'Razmakhnin Gena')

  console.log(patient)
} catch (error) {
  if (error instanceof HTTPError) {
    const exception = await error.response.json()
    console.dir(exception, { depth: 5 })
    return
  }

  console.dir(error, { depth: 10 })
}