Search Mailing List Archives

Limit search to: Subject & Body Subject Author
Sort by: Reverse Sort
Limit to: All This Week Last Week This Month Last Month
Select Date Range     through    

[bioontology-support] Questions regarding the REST API

John Zobolas john.zobolas at
Sun Nov 11 12:18:19 PST 2018

Hi Michael,

Thanks so much for the answers and very helpful indeed! Please see inline for further discussion/clarification on some of those.

BR, John.

From: Michael Dorf <mdorf at>
Sent: Saturday, November 10, 2018 12:46 AM
To: John Zobolas
Cc: support at
Subject: Re: [bioontology-support] Questions regarding the REST API

Hi John,

Thanks for contacting us. See my answers inline below.

On Nov 9, 2018, at 5:57 AM, John Zobolas <john.zobolas at<mailto:john.zobolas at>> wrote:


I am developing a module that's uses your API to get results back from different ontologies and I want to ask a few things:

  1.  ​I see that when I search for a string, in the results there is a property obsolete (e.g.<> which almost always (as far as I can tell) isfalse. Can I ever find it to be true (meaning that that entry is not used any more so I will have to prune that result)? Or you automatically filter the results to show only obsolete:falseones?

The results are by default filtered on obsolete:false. There is a parameter called also_search_obsolete={true|false} if you want a more granular control over this flag.

  1.  Is the URL parameter no_contexts=true equal to display_context=false (I accidentally discovered that they work the same but the first one is not mentioned in the documentation, so I should probably use the later!)

Both paramours work, but the correct one to use is display_context={true|false}, which is the one advertised in our documentation.

  1.  I was looking at the documentation in the available media types section, and I was wondering that if I send an HTTP request with method DELETE to a URL like or,<> will I be actually deleting that specific group/ontology? I mean do I even have the privileges to do that or is something that only an `admin` could do (because in the documentation it is not specified who can do what for every HTTP verb and media type).

You can create ontologies/groups programmatically using your own API key via a POST call, but you cannot delete anything from the system. That function is limited to admins only.

  1.  The format of error responses is always the same no matter what query I use in your provided REST service (an object with errors and status properties, the first having an array of Strings as a value and the second the status code/number as a value)?​​ E.g. what I will get when I hit:

Yes, the errors should all have a uniform response. If you notice otherwise, that would probably constitute a bug. Let us know if you find an error that deviates from this format.


"errors": [
     *   "You must provide a valid `acronym` to retrieve an ontology"
  *   "status": 404



"errors": [
     *   "The search query must be provided via /search?q=<query>[&page=<pagenum>&pagesize=<pagesize>]"
  *   "status": 400


  1.  If I have the acronym of an ontology, I can access (all) the classes: (e.g. The first result in the previous query has the prefLabel:FetalCellLine. So, if I query the: I get this one result and whatever property was empty in the 'classes query' result (e.g. definition:[ ]), it's not shown in the later query, right?

Correct. These two endpoints appear to have a slightly different handling of the empty fields. The classes endpoint displays empty lists, where as the search endpoint just drops the empty attributes from the response. Example:<>

  1.  Is there a way to get all the results from an ontology (paginated of course) through a query different than the one like /ontologies/:acronym/classes and have the results pruned (no empty properties) as when you query by search string?

You can try calling the search endpoint without passing in a search string and limiting the results to a specific ontology. You need to pass a “special” parameter called “ontology_types=ONTOLOGY” in order for the queriless search to work:

This will give you ALL results stored in our search index for the ontology NCIT. This isn’t the “advertised” method of getting all classes, rather a “workaround” that let’s you execute a search call without passing a query string.

Really helpful!!! I noticed also that when you do: you get a total count of 144695 classes, while the query returns 140329 as a total count and the difference must be that the first has the obsolete terms as well, right? Because if I do:, then I get 144695!

Is there a specific ordering on the returned results on the query: Are the results ordered by prefLabel or @id for example?(doesn't seem to be the case)

Also, does this query return all classes in all ontologies in BioPortal: ?
And if so, what ordering is applied to the results?

  1.  I have noticed that the @id in the results is not a unique id, right? For example, there are many results with this id:, belonging to different ontologies - and the difference between them is small, for example one result does not provide the definition while the other does.

Again, correct! The @id represents the class ID as defined in the original source ontology. The same class can be reused in multiple ontologies. The “unique” ID of a class in BioPortal is a combination of the @id and the ontology acronym, as in:<> Useful to know!

  1.  Is there a way to get results by id? Something like: /searchByID/id=URLid  (according to (7) this could result in more than 1 result) or /searchByID/ids={URLid1,URLid2,URLid3,…}?

Yes, you can pass the URL-encoded full ID in the “q” parameter to the /search endpoint:<>

Actually I kinda though that the `search?q=something` searched for `something` in the prefLabel and synonyms only! (but it seems this is not the case, since it searchs for a match with the @id as well :) Which other fields does it look for a match?
Also I noticed that the `something` must always be URL encoded (otherwise you get no results). Do you think that the `ontologies=GO,BAO` part should be also (for the comma mostly)?
Do you know if there is an id I can request that has more than 50 matches (a class that is included in more than 50 ontologies)? This would mean that I would have a second page of results (since the default pagesize is 50).

You cannot search by multiple IDs.

  1.  Is there a way to get results by a combination of id+ontology acronym? Something like /searchByIDAndOntology/id=URL&ontology=OntologyAcronym? Actually, if you merge the 2 last questions, what I am asking is this query: /searchByIDAndOntology/id=[list of URLids]&ontologies=[list of ontologies]? The nearest I found in the documentation was the query with the subtree_root_id which needs the search string (so I can't use it in my case). Also, this could cover the (6) if the list of ids is empty!

If you want to limit results to a given class within a given ontology(ies), just add the “ontologies=“BAO,DOID” to the query:,DOID
Here, is there a preferential sorting happening for these results (first BAO entry and then DOID for example? - though I see you get them the other way around)<>

Hope this helps! Feel free to reach out if you have further questions.


Michael Dorf
Chief Software Architect
The National Center for Biomedical Ontology
Stanford Biomedical Informatics Research
mdorf at<mailto:mdorf at>
O: 650-723-0357
M: 650-995-4374

​BR, John.
John Zobolas
PhD Student
Department of Biology, Faculty of Natural Sciences, NTNU
Department of Clinical and Molecular Medicine, Faculty of Medicine and Health Sciences, NTNU

bioontology-support mailing list
bioontology-support at<mailto:bioontology-support at>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the bioontology-support mailing list