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

Michael Dorf mdorf at
Fri Nov 9 15:46:10 PST 2018

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.

  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:<>

  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:<>

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<,DOID><>

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