ORTHOLOGY REST API

1. Usage of HTTP Verbs

The following table describes how the Orthology API interprets the HTTP verbs.

Table 1. HTTP Verbs
HTTP Verb	Usage
GET	GET is used to retrieve information without changing the state of the system.

Other verbs, such as DELETE, POST, UPDATE are not supported by Ortgology at present.

2. Pagination and Sorting

Most of the endpoints returning collections are paginated and can be sorted. If no parameters are specified, then the default ones are applied.

2.1. Pagination

The parameters to specify the pagination are:

Parameter

Description

page

Number of the page to retrieve. It starts with 0 (which is the default value).

size

Number of elements to retrieve.

Orthology api provides GET endpoints that provides the one to one orthologs data for the essential genes and the reference database services.

2.2. Fields

These are the fields you are going to see in the body of a request in a GET or in the payload for POST or PUT operations.

Path Type Description

Path	Type	Description
`[].humanGeneSymbol`	`String`	Human Gene Symbol
`[].hgncAccId`	`String`	Human Gene Accession Id
`[].humanSupportCountThreshold`	`Number`	Human Support Count Threshold
`[].humanCategoryForThreshold`	`String`	Human Category For Threshold
`[].humanOrthologsAboveThreshold`	`Number`	Human Orthologs Above Threshold
`[].category`	`String`	Category
`[].supportCount`	`Number`	Support Count
`[].isMaxHumanToMouse`	`String`	Is Max Human To Mouse
`[].isMaxMouseToHuman`	`String`	Is Max Mouse To Human
`[].mouseOrthologsAboveThreshold`	`Number`	Mouse Orthologs Above Threshold
`[].mouseCategoryForThreshold`	`String`	Mouse Category For Threshold
`[].mouseSupportCountThreshold`	`Number`	Mouse Support Count Threshold
`[].mgiGeneAccId`	`String`	Mouse Gene Accession Id
`[].mouseGeneSymbol`	`String`	Mouse Gene Symbol

[].humanGeneSymbol

String

Human Gene Symbol

[].hgncAccId

String

Human Gene Accession Id

[].humanSupportCountThreshold

Number

Human Support Count Threshold

[].humanCategoryForThreshold

String

Human Category For Threshold

[].humanOrthologsAboveThreshold

Number

Human Orthologs Above Threshold

[].category

String

3. ORTHOLOGS

This section describes the REST endpoints for orthologs in the system.

3.1. GET One To One Orthologs By Mouse Gene Symbol

Get All the one-to-one orthologs mapping by mouse gene symbol or symbol list. The mouse gene symbol list should be entered with , separated in the endpoint. Note:Parameter size can not be bigger than 600.

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/one_to_one/find_by_mouse_genes?genes=A1cf' -i -X GET \
    -H 'Authorization: None'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 405

[{"humanGeneSymbol":"A1CF","hgncAccId":"HGNC:24086","humanSupportCountThreshold":5,"humanCategoryForThreshold":"one-to-one","humanOrthologsAboveThreshold":1,"category":"GOOD","supportCount":11,"isMaxHumanToMouse":"max","isMaxMouseToHuman":"max","mouseOrthologsAboveThreshold":1,"mouseCategoryForThreshold":"one-to-one","mouseSupportCountThreshold":5,"mgiGeneAccId":"MGI:1917115","mouseGeneSymbol":"A1cf"}]

3.2. GET One To One Orthologs By Human Gene Symbol

Get All the one-to-one orthologs mapping by human gene symbol or symbol list. The human gene symbol list should be entered with , separated in the endpoint. Note:Parameter size can not be bigger than 600.

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/one_to_one/find_by_human_genes?genes=A1CF' -i -X GET \
    -H 'Authorization: None'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 405

[{"humanGeneSymbol":"A1CF","hgncAccId":"HGNC:24086","humanSupportCountThreshold":5,"humanCategoryForThreshold":"one-to-one","humanOrthologsAboveThreshold":1,"category":"GOOD","supportCount":11,"isMaxHumanToMouse":"max","isMaxMouseToHuman":"max","mouseOrthologsAboveThreshold":1,"mouseCategoryForThreshold":"one-to-one","mouseSupportCountThreshold":5,"mgiGeneAccId":"MGI:1917115","mouseGeneSymbol":"A1cf"}]

3.3. GET One To One Orthologs By MGI Accession Ids

Get All the one-to-one orthologs mapping by MGI accession id or MGI accession id list. The MGI accession id list should be entered with , separated in the endpoint. Note:Parameter size can not be bigger than 600.

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/one_to_one/find_by_mgi_ids?mgiIds=MGI:1917115' -i -X GET \
    -H 'Authorization: None'

Example Response

Unresolved directive in restapi.adoc - include::/Users/ogunes/Documents/orthology-api/target/generated-snippets/one-to-one-by-mgi-accession-ids/http-response.adoc[]

3.4. GET One To One Orthologs By HGNC Accession Id

Get All the one-to-one orthologs mapping by HGNC accession id or HGNC accession id list. The HGNC accession id list should be entered with , separated in the endpoint

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/one_to_one/find_by_hgnc_ids?hgncIds=HGNC:24086' -i -X GET \
    -H 'Authorization: None'

Example Response

Unresolved directive in restapi.adoc - include::/Users/ogunes/Documents/orthology-api/target/generated-snippets/one-to-one-by-hgnc-accession-ids/http-response.adoc[]

3.5. GET All Orthologs

Get All the one-to-one ortholog

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/find_all' -i -X GET \
    -H 'Authorization: None'

Example Response

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 590

{"_embedded":{"orthologDtoList":[{"humanGeneSymbol":"A1CF","hgncAccId":"HGNC:24086","humanSupportCountThreshold":5,"humanCategoryForThreshold":"one-to-one","humanOrthologsAboveThreshold":1,"category":"GOOD","supportCount":11,"isMaxHumanToMouse":"max","isMaxMouseToHuman":"max","mouseOrthologsAboveThreshold":1,"mouseCategoryForThreshold":"one-to-one","mouseSupportCountThreshold":5,"mgiGeneAccId":"MGI:1917115","mouseGeneSymbol":"A1cf"}]},"_links":{"self":{"href":"http://localhost:8080/api/ortholog/find_all?page=0&size=20"}},"page":{"number":0,"size":20,"totalElements":1,"totalPages":1}}

3.6. GET All Orthologs By MGI Ids

Get All the one-to-many orthologs mapping by MGI accession id or MGI accession id list. The MGI accession id list should be entered with , separated in the endpoint. Note:Parameter size can not be bigger than 600.

Example Request

Curl:

$ curl 'http://localhost:8080/api/ortholog/find_all_by_mgi_ids?mgiIds=MGI:1917115' -i -X GET \
    -H 'Authorization: None'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 405

[{"humanGeneSymbol":"A1CF","hgncAccId":"HGNC:24086","humanSupportCountThreshold":5,"humanCategoryForThreshold":"one-to-one","humanOrthologsAboveThreshold":1,"category":"GOOD","supportCount":11,"isMaxHumanToMouse":"max","isMaxMouseToHuman":"max","mouseOrthologsAboveThreshold":1,"mouseCategoryForThreshold":"one-to-one","mouseSupportCountThreshold":5,"mgiGeneAccId":"MGI:1917115","mouseGeneSymbol":"A1cf"}]

3.7. GET All Orthologs As TSV File

Get All the orthologs as TSV file

Example Request

/api/ortholog/write_to_tsv_file

=== GET All One To One All Orthologs As TSV File
Get All the one-to-one All orthologs as TSV file

===== Example Request

/api/ortholog/one_to_one/all/write_to_tsv_file

3.8. GET All One To One IMPC Orthologs As TSV File

Get All the one-to-one IMPC (selects protein coding and miRNA genes) orthologs as TSV file

Example Request

/api/ortholog/one_to_one/impc/write_to_tsv_file

4. Lastest updates

2024-05-02: - one_to_one/all/write_to_tsv_file endpoint added.
2022-06-29: - one_to_one/impc/write_to_tsv_file endpoint added.
2022-06-15: - find_all_by_mgi_ids added.