ARS Query Process

POST a TRAPIformatted query such as:

{
      "message": {
        "query_graph": {
          "nodes": [
            {
              "id": "n0",
              "set": false,
              "type": "named_thing"
            },
            {
              "id": "n1",
              "curie": "HP:0040128",
              "set": false
            }
          ],
          "edges": [
            {
              "id": "e0",
              "source_id": "n1",
              "target_id": "n0"
            }
          ]
        }
      }
}

to https://ars.transltr.io/ars/api/submit

E.g. curl -d @query.json https://ars.transltr.io/ars/api/submit

You should then receive a response similar to this one

{
  "model": "tr_ars.message",
  "pk": "7d399515-6219-4340-82fc-ab451ab18744",
  "fields": {
    "name": "",
    "code": 200,
    "status": "Running",
    "actor": 9,
    "timestamp": "2020-12-01T20:49:31.702Z",
    "data": {
      "message": {
        "query_graph": {
          "nodes": [
            {
              "id": "n0",
              "set": false,
              "type": "named_thing"
            },
            {
              "id": "n1",
              "curie": "HP:0040128"
            }
          ],
          "edges": [
            {
              "id": "e0",
              "source_id": "n1",
              "target_id": "n0"
            }
          ]
        }
      }
    },
    "url": null,
    "ref": null
  }

The highlighted primary key above can be used to access the results of the query at

https://ars.transltr.io/ars/api/messages/7d399515-6219-4340-82fc-ab451ab18744?trace=y

The results page should look something like this:

{
message: "d7b6691b-6584-4d5c-a9c9-3210f337063b",
status: "Running",
actor: 
{
pk: 9,
channel: "general",
agent: "ars-default-agent",
path: ""
},
children: 
[
{
message: "df61104f-75e5-4401-a868-ebb9d5c21978",
status: "Done",
actor: 
{
pk: 1,
channel: "general",
agent: "ara-aragorn",
path: "runquery"
},
children: [ ]
},

Note that each of the children has a PK similar to the one for your original query. Each of these children entries in the JSON corresponds to an individual result set from a different Translator tool. You can access the individual results in the same way as the overall result set, but with the omission of trace=y from the URL, like this: https://ars.transltr.io/ars/api/messages/980bf357-3004-4ce3-8389-7843894b51e8

In the individual result sets, there are three primary components:

query_graph

This is likely just a restatement of the query graph that you provided with your initial POST to the ARS. However, it is possible for the component answering the query to make alterations to the query_graph. In this case, the query_graph displayed here will be the modified query_graph (corresponding to the query that the service actually answered)

results

The results section contains individual results. These results are somewhat abbreviated and will be described with node and edge bindings. These "bindings" correspond to the identifiers for the more detailed entry describing the node or edge in the knowledge_graph section.

knowledge_graph

This is an entity that represents all of the nodes and edges present in any result. They are presented here in detail to save possible duplication in the results (in the relatively common case that a node or edge appears in multiple results)

The last submitted query to the ARS can be found at https://ars.transltr.io/ars/app/status which will show the number of results from each provider as well as linking out to those result pages.

Common Errors:

Receiving a message of "Not a valid Translator query" from the ARS indicates a problem with the query graph failing validation. This is likely due to the query_graph not being wrapped in a "message" element

Receiving a 500 server error typically indicates an invalid JSON being sent as the query graph. JSONs can be validated easily here: https://jsonlint.com/