Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: /api/v1/strucvars/csq endpoint with OpenAPI (#607) #612

Merged
merged 5 commits into from
Nov 11, 2024
Merged

feat: /api/v1/strucvars/csq endpoint with OpenAPI (#607) #612

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b612ae3
feat: provide genes/transcripts endpoint with openapi (#605)
holtgrewe Nov 11, 2024
cd834b6
Merge remote-tracking branch 'origin/main' into 605-provide-endpoint-…
holtgrewe Nov 11, 2024
80902db
wip
holtgrewe Nov 11, 2024
c89ff6f
feat: /api/v1/strucvars/csq endpoint with OpenAPI (#607)
holtgrewe Nov 11, 2024
9cab99e
Merge remote-tracking branch 'origin/main' into 607-provide-endpoint-…
holtgrewe Nov 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions openapi.schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,59 @@ info:
name: MIT
version: 0.29.6
paths:
/api/v1/strucvars/csq:
get:
tags:
- strucvars_csq
summary: Query for consequence of a variant.
operationId: strucvarsCsq
parameters:
- name: genome_release
in: query
description: The assembly.
required: true
schema:
$ref: '#/components/schemas/GenomeRelease'
- name: chromosome
in: query
description: Chromosome.
required: true
schema:
type: string
- name: start
in: query
description: 1-based start position.
required: true
schema:
type: integer
format: int32
- name: stop
in: query
description: 1-based stop position, ignored for INS.
required: false
schema:
type: integer
format: int32
nullable: true
- name: sv_type
in: query
description: The variant type to use for annotation.
required: true
schema:
$ref: '#/components/schemas/StrucvarsSvType'
responses:
'200':
description: Strucvars consequence information.
content:
application/json:
schema:
$ref: '#/components/schemas/StrucvarsCsqResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomError'
Comment on lines +12 to +64
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add missing query parameter and enhance endpoint documentation.

The endpoint specification needs several improvements:

  1. The as= parameter mentioned in PR comments is missing from the specification.
  2. Add validation for numeric parameters:
    • start: Add minimum value (should be >= 1)
    • stop: Add minimum value (should be >= 1)
  3. Add common HTTP status codes:
    • 400: For invalid input parameters
    • 404: For when no results are found
  4. Add example requests and responses using OpenAPI's example or examples field
      - name: start
        in: query
        description: 1-based start position.
        required: true
        schema:
          type: integer
          format: int32
+         minimum: 1
+         example: 1000000
      - name: stop
        in: query
        description: 1-based stop position, ignored for INS.
        required: false
        schema:
          type: integer
          format: int32
          nullable: true
+         minimum: 1
+         example: 1000100
+     - name: as
+       in: query
+       description: Output format specification
+       required: false
+       schema:
+         type: string
+         enum: [vcf, json]
+         default: json
      responses:
        '200':
          description: Strucvars consequence information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrucvarsCsqResponse'
+             example:
+               version: {...}
+               query: {...}
+               result: [...]
+       '400':
+         description: Invalid input parameters.
+         content:
+           application/json:
+             schema:
+               $ref: '#/components/schemas/CustomError'
+       '404':
+         description: No results found.
+         content:
+           application/json:
+             schema:
+               $ref: '#/components/schemas/CustomError'
        '500':
          description: Internal server error.

Committable suggestion skipped: line range outside the PR's diff.

/api/v1/versionsInfo:
get:
tags:
Expand Down Expand Up @@ -62,6 +115,12 @@ components:
type: string
description: Version of the Ensembl database, if any.
nullable: true
GenomeRelease:
type: string
description: Select the genome release to use.
enum:
- grch37
- grch38
Comment on lines +118 to +123
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Remove duplicate schema definition.

The GenomeRelease schema duplicates the existing Assembly schema. Both define the same enum values. Consider using the existing Assembly schema instead.

-    GenomeRelease:
-      type: string
-      description: Select the genome release to use.
-      enum:
-      - grch37
-      - grch38

Then update references to use Assembly:

-          $ref: '#/components/schemas/GenomeRelease'
+          $ref: '#/components/schemas/Assembly'

Committable suggestion skipped: line range outside the PR's diff.

SoftwareVersions:
type: object
description: Software version specification.
Expand All @@ -75,6 +134,83 @@ components:
hgvs_rs:
type: string
description: Version of the `hgvs` crate.
StrucvarsCsqQuery:
type: object
description: Query parameters of the `/api/v1/strucvars/csq` endpoint.
required:
- genome_release
- chromosome
- start
- sv_type
properties:
genome_release:
$ref: '#/components/schemas/GenomeRelease'
chromosome:
type: string
description: Chromosome.
start:
type: integer
format: int32
description: 1-based start position.
stop:
type: integer
format: int32
description: 1-based stop position, ignored for INS.
nullable: true
sv_type:
$ref: '#/components/schemas/StrucvarsSvType'
StrucvarsCsqResponse:
type: object
description: Response of the `/api/v1/strucvars/csq` endpoint.
required:
- version
- query
- result
properties:
version:
$ref: '#/components/schemas/VersionsInfoResponse'
query:
$ref: '#/components/schemas/StrucvarsCsqQuery'
result:
type: array
items:
$ref: '#/components/schemas/StrucvarsGeneTranscriptEffects'
description: The resulting records for the affected genes.
StrucvarsGeneTranscriptEffects:
type: object
description: Explanation of transcript effect per individual gene.
required:
- hgnc_id
- transcript_effects
properties:
hgnc_id:
type: string
description: HGNC identifier
transcript_effects:
type: array
items:
$ref: '#/components/schemas/StrucvarsTranscriptEffect'
description: Transcript effects for the gene.
StrucvarsSvType:
type: string
description: Structural Variant type.
enum:
- DEL
- DUP
- INS
- INV
- BND
StrucvarsTranscriptEffect:
type: string
description: Enumeration for effect on transcript.
enum:
- transcript_variant
- exon_variant
- splice_region_variant
- intron_variant
- upstream_variant
- downstream_variant
- intergenic_variant
VersionsInfoResponse:
type: object
description: Response of the `/api/v1/version` endpoint.
Expand Down
Loading
Loading