In the below tables:
- 'sname' (sample name) is a guuid in the production system using this server, but it is does not have to be such.
- 'threshold' is an integer, e.g. 12, in SNP.
- 'cutoff' is a floating point number betwen 0 and 1, which reflects a quality metric on the samples (the proportion of Ns)
- 'dna' is a sequence of bases A,C,G,T,N, or -.
- N/A refers to 'not available' in v1. Version numbering refers to the API version, not to the findNeighbour version.
| v2 route | v1 route (fully functional, all use GET) | XMLRPC Endpoint | Function | Example responses | Note | cf. EW1 |
|---|---|---|---|---|---|---|
| /v2/server_config [GET] | N/A | server_config | returns the server config file | {"DESCRIPTION":"A test server operating in on localhost for tb testing","PORT":8184, "IP":"127.0.0.1", ...., "LOGLEVEL":"INFO" } | Allows identification of what server is on what port; however, may contain highly sensitive internal information, including database passwords; disable outside a trusted setting | New in findNeighbour2 |
| /v2/server_time [GET] | N/A | server time | returns the server's internal time | {"server_time": "2017-04-27T11:51:35.771625"} | Mainly useful to test server availability | New in findNeighbour2 |
| /v2/server_memory_usage [GET] | N/A | server_memory_usage | returns memory usage by the server process | {"memory_units": "bytes", "maximum_resident_set_size": 34840052, "note": "Values are as returned by the python3 resource module for the server process only. Please see https://docs.python.org/3/library/resource.html for more information"} | Memory used by other processes e.g. databases is not included. The statistic returned is the 'maximum ever' memory usage by the server. Current memory usage may be smaller. | New in findNeighbour2 |
| /v2/insert [POST] | N/A | insert | inserts a sample called sname containing a mapped DNA sequence dna | ['OK'] | Parameters are in italics. Please see docs for example client code to use the xmlrpc server. | Identical XMLRPC method in both versions; RESTful endpoint exposed in findNeighbour2 |
| /v2/nucleotides_excluded [GET] | N/A | server_nucleotides_excluded | returns the nucleotides which are being masked by the server when it performs sequence comparisons | [8000,8001,...] | Useful for ensuring server and client use the same masking | Not relevant in EW1, which requires pre-masked sequences |
| /v2/sname/exists [GET] | /sample/walks/processed | exist_sample | check whether the sample identified by sname sname exists in the server. | {'True'} or {'False'} | Only snames are accepted as identifiers | Identical query and response from both versions |
| /v2/sname/neighbours_within/threshold [GET] | /sample/neighbours/ /sample/findneighbour/snp/ /sample/walks/snp [GET] | query_get_value_snp_filter | identify sname's neighbours closer than threshold iff the neighbours have a quality score more than quality_cutoff. If quality_cutoff is not supplied, 0.85 is used. Two formats are possible, 1 and 2. 1 is the default, and is compatible with Elephantwalk1. | Format 1: ["OK", [["fc3b2c0b-1886-4ff9-8d67-6d6f7674a910"], ["b1a2bfa3-3609-46ad-be8b-3dc059722128"]]] or ['Bad', 'bad sequence']; Format 2: ["OK", [["fc3b2c0b-1886-4ff9-8d67-6d6f7674a910", 2, 28701, 29410, 34433], ["b1a2bfa3-3609-46ad-be8b-3dc059722128", 2, 33687, 29410, 39088]]] or ['Bad','bad sequence'] | - | Use format=1 (or omit a format parameter) for compatibility with EW1. EW2 returns, if format = 2, additional information related to Ns in sequences. |
| /v2/guids [GET] | /sample/guids | get_all_guids | list of snames in the server | [ {"guid": "7b2a6689-add4-4795-8955-7a56d48710e6"}, .... , {"guid": "987ee0ba-c65a-4747-9419-42c0dfc3909d"}, {"guid": "dd14c0fd-12bb-472c-9917-c66cd28631e7"}, {"guid": "8667eca5-ba7f-4aa2-8df0-4e1f36689b49"}]] | - | Identical in both versions |
| /v2/guids_with_quality_over/cutoff [GET] | /sample/guids_cutoff | get_all_filtered_guids | list of guids in the server with quality score (proportion of Ns) more than cutoff | ["3564e811-380e-43be-9455-54ad5081ba0b", "4681f9ae-aa1f-4dc0-97cb-3bfaed5de812", ... , "c759c44d-9072-436c-8de5-59ab70f0d82b", "4ae516cc-eeef-40ea-806c-4f35a3860e4d"] | - | Identical in both versions |
| /v2/guids_and_examination_times [GET] | /sample/guids_and_time | get_all_guids_examination_time | list of all snames on the server and their examination times | {"sname": "987ee0ba-c65a-4747-9419-42c0dfc3909d", "examinationTime": "2017-04-12T02:20:06.296760"}, {"sname": "dd14c0fd-12bb-472c-9917-c66cd28631e7", "examinationTime": "2017-04-12T02:20:09.573247"}, {"sname": "8667eca5-ba7f-4aa2-8df0-4e1f36689b49", "examinationTime": "2017-04-12T02:20:12.275453"}] | - | Identical in both versions |
| /v2/annotations [GET] | sample/annotation | get_all_annotations | all meta data on all samples | json object containing a list of sname: metadata dictionaries | Returned object is large, and query is relatively slow. | Identical between both versions |
| /v2/sname1/sname2/detailed_comparison [GET] | N/A | query_get_detail | returns positions of variation between sname1 and sname2 | json object containing positions of variation in both samples | Query is fast ( ~ 50msec per comparison), and includes information on all variation between the two sequences | New in FindNeighbour2. |
| /v2/neighbours_within/threshold [GET] | N/A | get_all_values | returns pairs of samples whose snp difference is less than or equal to threshold | json object containing pairs of samples, and the distance between them | Identical between both versions |