Start a new topic

Single v Batch Target API response format

Why are the response formats for batch and single target response shown as being different in the API docs. Surely the batch response is really just an array of single target responses? The batch response has "sameAs" & "mappingRelation" which don't seem to be listed in the API docs but don't have "primaryTopic" for each response within the items array which of course means that writing parsers is made harder :(

Anyway, I just noticed that the chembl info now in the "mappingRelation" block. Why? For an example, look at the following URI http://www.conceptwiki.org/concept/00059958-a045-4581-9dc5-e5a08bb0c291 and the corresponding single:

https://beta.openphacts.org/1.4/target?uri=http%3A%2F%2Fwww.conceptwiki.org%2Fconcept%2F00059958-a045-4581-9dc5-e5a08bb0c291&app_id=1c22cbe7&app_key=167a3a3d8539b5d85280e7178f4e62ab&_format=json


and batch calls:


https://beta.openphacts.org/1.4/target/batch?uri_list=http%3A%2F%2Fwww.conceptwiki.org%2Fconcept%2F00059958-a045-4581-9dc5-e5a08bb0c291&app_id=1c22cbe7&app_key=167a3a3d8539b5d85280e7178f4e62ab&_format=json


Clarifies that I don't understand SPARQL enough :) Why don't we just have the 'batch' call and remove the target info one. Target info would then just be a 'batch' call with 1 URI. Could do the same for compound info/batch.

Anyway, I still don't understand why the batch call isn't just multiple info calls. Still confused why the chembl bits don't appear in exactMatch. Are you implying that anything that can appear in an exactMatch block can appear in the mappingRelation part (singeton or array?) depending on what the URI is?

The different mapping predicates (sameAs, mappingRelation) as well as the other differences between batch calls and those for single entity are due to design limitations associated with RDF/SPARQL, since all API results are generated from RDF responses to SPARQL queries.


More specifically: 

  • foaf:primaryTopic : This property is only used for "Item" LDA endpoints, since it can only have a single value as an owl:FunctionalProperty. Moreover, its domain is foaf:Document; i.e. a page of the Open PHACTS API . Batch calls were designed based on LDA "List" endpoints, where a page is defined as a list of "items", e.g. Compound Pharmacology: List. Since an item on the list is not a foaf:Document, we can't apply this property to the items.

  • Mapping properties : In Open PHACTS, the IMS is used to map input URIs to those that expected to occur in the source datasets. When a single URI is used as input, we can expect that all returned URIs match each other. This allows the LDA to replace the actual IMS properties with skos:exactMatch, under the context of the active lens. This assumption is false for Batch calls, as a single Batch SPARQL query will contain URIs for multiple entities from each source. Dealing with this in the same way would result in skos:exactMatch links between different entities. To overcome this, the SPARQL query doesn't generate any mapping links, and instead the IMS (RDF) response is included directly with the results. This has the side effect that we expose the same predicates as those that appear in the linkset the IMS used.

These issues were pointed out before developing the Batch calls, the decision made at the time was that the advantage of having Batch methods available was worth the differences in the formatting. We also discussed extending the IMS to allow for the output mapping predicate to be set via a parameter. It was argued that a more specific response (i.e. using the source mapping predicates) may be preferable in certain cases, and deferred a decision until we had some feedback on the current format.

Hope this clarifies somewhat :) 
Login or Signup to post a comment