Modelling of api responses for focus objects

Endpoints for focus objects

Big decisions

• Should we rename the thing that used to be called ensembl_object and is currently called object to feature? (ask Andy?)
• Concern related to above: can a focus object that is a region be considered a feature?
• Since region in core data language means something different than a region in our language (which is a focus object), should we rename region to slice?
• Alternatively, should we rename region to feature_region (or feature_slice), so that we don't end up with a slice data structure that has a field called slice?
• Do focus objects need to know which track they belong to? (E.g. what should happen to BRCA2 track when we hide protein-coding genome-wide track)?

General questions for backend

1. What is the convention for endpoint path names? Example:

/api/object/info?object_id=triticum_aestivum_GCA_900519105_1:gene:TraesCS3D02G273600 (this is how the paths to the few endpoints we currently have are typically structures) or /api/objects/:object_id/info (this is more idiomatically RESTful)

2. Should we use namespacing in the response payload?

Example:

{
  "feature": {
    
  }
}

Feature info endpoint

Purpose: get full information about a feature to show when you open Track Drawer.

/api/feature/info?feature_id=triticum_aestivum_GCA_900519105_1:gene:TraesCS3D02G273600

Api response

enum Strand {
  FORWARD,
  REVERSE,
  BOTH
}

enum SupportLevel {
  CANONICAL,
  MANE_SELECT,
  ...
}

enum BiotypeCode {
  PROTEIN_CODING
  NON_CODING
  ...
}

type Slice = {
  location: {
    start: number, // e.g. 379535906,
    end: number // e.g. 379539827,
    strand: Strand | null
  },
  region: {
    region_name: string, // "3D",
    region_code: string, // out of an enum, e.g. 'chromosome'
  }
},


// see question whether response fields should be namespaced under `feature` above
type GeneResponse = {
  feature_id: string, // e.g. triticum_aestivum_GCA_900519105_1:gene:TraesCS3D02G273600
  feature_code: 'gene',
  biotype_code: BiotypeCode, // "Protein coding",
  feature_description: string | null, // "Heat shock protein 101 "
  genome_id: string, // "triticum_aestivum_GCA_900519105_1",
  feature_label: string, // "TraesCS3D02G273600",
  slice: Slice, // see type abover
  stable_id: string, // "TraesCS3D02G273600",
  versioned_stable_id: string
}

// TODO: review transcript response (we haven't spent much time on that)
type TranscriptResponse = {
  feature_id: string, // e.g. triticum_aestivum_GCA_900519105_1:transcript:TraesCS3D02G273600
  feature_code: 'transcript',
  biotype_code: BiotypeCode, // "Protein coding",
  feature_description: string | null, // "Heat shock protein 101 "
  genome_id: string, // "triticum_aestivum_GCA_900519105_1",
  feature_label: string, // "TraesCS3D02G273600",
  slice: Slice, // see type above
  stable_id: string, // "TraesCS3D02G273600",
  support_level_code: SupportLevel,
  versioned_stable_id: string
}

type VariantResponse = {
  // ???
}

Focus feature (provisional name)

Purpose: show focus feature and list of features associated with it. Show information about focus feature in the track panel and in the navigation bar

/api/feature/focus_feature?feature_id=triticum_aestivum_GCA_900519105_1:gene:TraesCS3D02G273600

Api response

type FocusGeneFeature = {
  feature_id: string, // e.g. triticum_aestivum_GCA_900519105_1:gene:TraesCS3D02G273600
  feature_code: 'gene',
  biotype_code: BiotypeCode, // "Protein coding",
  genome_id: string, // "triticum_aestivum_GCA_900519105_1",
  feature_label: string, // "TraesCS3D02G273600",
  slice: Slice, // see type abover
  stable_id: string, // "TraesCS3D02G273600",
  versioned_stable_id: string
}

type FocusTranscriptFeature = {
  feature_id: string, // e.g. triticum_aestivum_GCA_900519105_1:transcript:TraesCS3D02G273600
  feature_code: 'transcript',
  biotype_code: BiotypeCode, // "Protein coding",
  genome_id: string, // "triticum_aestivum_GCA_900519105_1",
  feature_label: string, // "TraesCS3D02G273600",
  slice: Slice, // see type above
  support_level_code: SupportLevel,
  stable_id: string, // "TraesCS3D02G273600",
  versioned_stable_id: string
}

type GeneResponse = FocusGeneFeature & {
  associated_features: {
    transcripts: FocusTranscriptFeature[] // first transcript is shown by default; only one transcript is shown
  }
}

type TranscriptResponse = FocusTranscriptFeature & {
  associated_features: {
    gene: FocusGeneFeature 
    transcripts: FocusTranscriptFeature[] // first transcript is shown by default; only one transcript is shown
  }
}

type SliceResponse = {
  feature_code: 'slice',
  feature_id: string, // e.g. triticum_aestivum_GCA_900519105_1:slice:13:1234-45667
  genome_id: string, // "triticum_aestivum_GCA_900519105_1",
  slice: Slice, // see type above
}

type Response = GeneResponse | TranscriptResponse | SliceResponse;