API Specs for 1st version of DD-Code POC

api_contracts.md

+# API Specifications
+
+#### 1. Get all Species
+
+* API Route: `/api/v0/species`
+* Description: An aggregation of all species in our database; for filters
+* Method: `GET`
+* Response: 
+    * Data Type: dictionary
+    * Keys: 
+        * `count`: integer
+        * `data`: list of dictionary
+            * `name`: string
+            * `tax_id`: string
+
+
+#### 2. List Condensates
+
+* API Route: `/api/v0/condensates`
+* Description: Get paginated list of  condensates matching the mentioned query parameters
+* Method: GET
+* Query Parameters: 
+    * `query`: string (Text search)
+    * `species_tax_id`: string
+    * `count`: integer
+    * `page`: integer
+    * `fields`: list of str
+* Response: 
+    * Data Type: dictionary
+    * Keys: (Can be restricted to `fields`)
+        * `count`: integer
+        * `prev_page`: string (Link)
+        * `next_page`: string (Link)
+        * `data`: list of dictionary
+            * `name`: string
+            * `species_tax_id`: string
+            * `species_name`: string
+            * `protein_count`: integer
+            * `unique_name`: string
+
+
+#### 3. Details: Condensates
+
+* API Route: `/api/v0/condensate/<unique_name>`
+* Description: Get details of a given condensate
+* Method: GET
+* Query Parameters:
+    * `fields`: list of str
+* Response: 
+    * Data Type: dictionary
+    * Keys: (Can be restricted to `fields`)
+        * `data`: dictionary
+            * `name`: string
+            * `species_tax_id`: string
+            * `species_name`: string
+            * `protein_count`: integer
+            * `proteins`: list of strings (uniprot_id)
+
+
+
+#### 4. List Proteins
+
+* API Route: `/api/v0/proteins`
+* Description: Get paginated list of proteins matching the mentioned query parameters
+* Method: GET
+* Query Parameters: 
+    * `query`: string (Text search)
+    * `species_tax_id`: string
+    * `count`: integer
+    * `page`: integer
+    * `fields`: list of str
+* Response: 
+    * Data Type: dictionary
+    * Keys: (Can be restricted to `fields`)
+        * `count`: integer
+        * `prev_page`: string (Link)
+        * `next_page`: string (Link)
+        * `data`: list of dictionary
+            * `name`: string
+            * `species_tax_id`: string
+            * `species_name`: string
+            * `sequence`: string
+            * `uniprot_id`: string
+            * `uniprot_readable_id`: string
+            * `gene_name`: string
+            * `ensembl_id`: string
+            * `ensembl_gene_id`: string
+            * `sequence`: string
+
+#### 5. Details: Proteins
+
+* API Route: `/api/v0/protein/<uniprot_id>`
+* Description: Get details of a given protein
+* Method: GET
+    * `fields`: list of str
+* Response: 
+    * Data Type: dictionary
+    * Keys: (Can be restricted to `fields`)
+        * `data`: dictionary
+            * `name`: string
+            * `species_tax_id`: string
+            * `species_name`: string
+            * `sequence`: string
+            * `uniprot_id`: string
+            * `uniprot_readable_id`: string
+            * `gene_name`: string
+            * `ensembl_id`: string
+            * `ensembl_gene_id`: string
+            * `sequence`: string
+            * `llps_ptms`: list of dict
+                * `name`: str
+                * `position`: string
+                * `enzyme`: string
+                * `effect_type`: string
+                * `effect_description`: string
+                * `function`: string
+
+
+
+### Errors:
+
+* All error responses have non 2XX status code
+* Response:
+    * Data Type: dictionary
+    * Keys:
+        * `code` (The following headings)
+        * `message` (Human readable error message with possible solution)
+
+
+##### 1. NOT FOUND
+
+* Status Code: 404
+* Cases: 
+    1. When a given route doesnt exists
+    2. When given records of details page doesnt exits
+    
+    
+##### 2. BAD REQUEST
+
+* Status Code: 400
+* Cases:
+    1. When `filter` attributes dont exist
+    2. When a `field` for projection doesnt exists
+    3. When data type of `filter` values are wrong
+    
+    
+##### 3. SERVER ERROR
+
+* Status Code: 500
+* Cases:
+    All unhandled server-side errors
\ No newline at end of file