Skip to content

Developer

Jump to bottom
Pierfrancesco Tommasino edited this page Feb 26, 2021 · 34 revisions

Programming with the EcoPortal API

Programming with the EcoPortal API

All the content that the EcoPortal uses (and more!) is available via REST services by means you can:

  • access all EcoPortal semantic resources, their different versions, and metadata for those versions;
  • access information about any semantic resource concept in EcoPortal (with definitions, synonyms, and other properties);
  • search across all semantic resources in EcoPortal;
  • get hierarchy information for EcoPortal semantic resources (such as parents, children, or siblings of a class, roots or leaves of a class hierarchy).

The EcoPortal REST API to access information is available here: http://ecoportal.lifewatch.eu:8080/documentation

  • Getting an API key

    Use of the EcoPortal REST APIs requires an API key. To retrieve your API key you have to be logged in the EcoPortal website where the key will be shown in plain text in your account page (see figure below). If you don't have an account, you need to create one.

    api key image

  • Using EcoPortal Technology In Your Project

    There are several ways in which you can use the EcoPortal technology for your own website or in your application. Here some use cases:

    • I have a list of terms that were used to annotate a dataset, how can I see if any of these terms exist in standard semantic resources? Use the “Search” web service to search terms in all EcoPortal semantic resources. If you have a limited number of terms, searching each one individually via the EcoPortal Search tool with the user interface may be sufficient. Otherwise, for a long list of terms, use the “Search” web service directly.

    • I would like to find all the terms mapped from my semantic resource to other semantic resources in EcoPortal. Use the “Mapping” web service to find terms in other EcoPortal semantic resources that are similar to the terms in your semantic resource. These mappings include mappings include those generated manually (DbXrefs) and programatically (LOOM).

    • I have a web form including text fields which I would like to populate with semantic resource terms, e.g., to select relevant terms from a specific EcoPortal semantic resource. Use the “Autocomplete” widget. Click on the "Get Code" button for the code and instructions on how to add this JavaScript to your web form.

    • I would like to add the graph displaying my semantic resource on my website. Use the “Visualization” widget. Click on the "Get Code" button for the code and instructions on how to add this JavaScript to your website.

    • I would like to get all terms from a semantic resource and re-format the data to use in my own system. Use the “Get All Terms” web service to get all the terms and properties for the semantic resource that you are interested in.

    • I need to navigate through a semantic resource and go through the semantic resource hierarchy for my software application. Is there a web service to do this? Use the “Get All terms” web service.

    • How can I limit the selection of semantic resources used with the EcoPortal Annotator to a given Category or Domain? Use the “List all semantic resources” and “Get Groups/Domains” web service to identify the group/domain of interest.

  • EcoPortal Widgets

    EcoPortal widgets are snippets of HTML or JavaScript code that you can embed inyour website/web form to use the EcoPortal functionalities. Using EcoPortal widgets is just one of the ways in which you can use EcoPortal technologies on your website/application.

    • How to use EcoPortal Widgets

      You can add any EcoPortal widget to your HTML page or web form by following these steps:
      • find the semantic resource that you are interested in by browsing the list of EcoPortal semantic resources (e.g., Fish Traits Thesaurus);
      • click on the semantic resource name to get to the page with Details for that semantic resource (e.g., the Details for Fish Traits Thesaurus);
      • in the semantic resource details page, go to the Widgets tab;
      • select the widget that you want to use;
      • click the button below the widget to get usage instructions.

    • Types of EcoPortal Widgets and use cases

      • Term-selection field on a form: you can add a text field to your web form that will allow users to enter a term from a controlled vocabulary (e.g., terms from a single semantic resource)

        • Example use case: let us suppose that you are running a tissue microarray database and that users can upload sample descriptions to your database by means of a web form. Usually, there is a field to specify the diagnosis related to the tissue sample that the user is filling in. This field is often a text-box or a dropdown menu, populated with a list of controlled terms. The free text-box is prone to errors, while the dropdown becomes unmanageable with too many terminologies. The EcoPortal term-selection widget allows users to easily select a term from an ontology or a controlled vocabulary to fill in the specific field. For example, when the user starts typing "fish", the term "fish traits'' pops up.
        • What does the term-selection field get you:
          • auto-complete the text field so that you don't need to type the whole term;
          • the controlled vocabulary provides consistency in the manner in which different users use a specific term;
          • when a new version of your controlled vocabulary becomes available in EcoPortal, the widget will automatically use that new version.

      • Semantic resource search widget: you can add a search box to your website that will allow users to search a specific EcoPortal semantic resource. When the user selects the term of interest (with the help of the auto-complete feature), she/he can move directly to the EcoPortal summary page of the corresponding concept.

      • Semantic resource visualization widget: you can put a widget on your website that shows your semantic resource of interest, or a part of it, and obtain the same result as in the "Visualize" tab in EcoPortal.

      • EcoPortal Ontology Tree Widget: you can put a widget on your website that displays the semantic resource tree, or a part of it, with the same result obtained in the "Visualize" tab in EcoPortal.

      • Term-selection field on a form

        To add a field to your web form that allows users to retrieve a term from the semantic resource of interest, do the following:

        • download the form_complete.js file and put it on your server;
        • in the header of the page where you want the field, include the form_complete.js file;
        • in the form, specify the field class in the following format: bp_form_complete-{semantic_resource_acronym_list}-{value}
          • Example: bp_form_complete-FISHTRAITS-uri will use FISH TRAITS Thesaurus (the acronym is FISHTRAITS) and will put the term URI in the field after the user selects the term from the pull-down list
          • Note: In addition to single ontology IDs, you can use a list: bp_form_complete-FISHTRAITS, ENVTHES-uri
          • OR you can use 'all' to search across all EcoPortal semantic resource: bp_form_complete-all-uri
        • you can use the following parameters to select which value will be placed into the user-visible input field:

        • Auto-generated hidden form elements In addition to the input element you defined, there are four hidden form elements that are automatically created and set when users select a term from the list. For example, if you create a field with this code:

          <input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>

          The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):

          
 <input type="hidden" id="a_ecoportal_preferred_name">
 <input type="hidden" id="a_ecoportal_concept_id">
 <input type="hidden" id="a_ecoportal_ontology_id">
 <input type="hidden" id="a_ecoportal_full_id">
        • Optional attributes

          • Include term definitions. Use data-bp_include_definitions="true" to display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with definitions, in the FISHTRAITS Thesaurus: <input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-FISHTRAITS-name"/>

          • Limit search to terms below a root term. Use data-bp_search_branch="{class_id}" (replace {class_id} with the class ID for the term to use as the branch root. For example, use this code to limit the search for 'FISH' to terms within the 'Fish Trait' branch of the FISHTRAITS Thesaurus:
            <input type="text" name="n" data-bp_search_branch="Fish Trait" class="bp_form_complete-FISHTRAITS-name"/>

          • Object types:

            • Search 'class' and 'property' objects. Use data-bp_objecttypes="class,property". For example, use this code to search for 'function' among both 'class' and 'property' objects from the "Adverse Event Reporting Ontology". <input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/>

            • Search only 'property' objects. Use data-bp_objecttypes="property". For example, use this code to search for 'function' among 'class' and 'property' objects from the "Adverse Event Reporting Ontology":

              <input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/>

            • Search 'class' and 'individual' objects. Use data-bp_objecttypes="class,individual".For example, use this code to search for 'seizure' among 'class' and 'individual' objects from the "Adverse Event Reporting Ontology":

              <input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/>

            • Search only 'individual' objects. Use data-bp_objecttypes="individual".For example, use this code to search for 'seizure' only among 'individual' objects from the "Adverse Event Reporting Ontology":

              <input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/>

      • Semantic resource search widget

        To add a search widget to your HTML page that allows users to search for a specific semantic resource:

        • download the quick_jump.js file and put it on your server;

        • copy the code below and paste it to your HTML page.

          
 <div id="bp_quick_jump"></div>
 <script type="text/javascript">
   var BP_ontology_id = "FISHTRAITS";
 </div>
 <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>

        • Note: if you want to use Quick Jump across multiple semantic resources:

          • enter a comma-separated list of semantic resource ids: var BP_ontology_id = "FISHTRAITS,ENVTHES";
          • you can set the variable to 'all' to search all semantic resources in EcoPortal: var BP_ontology_id = "all";

        • update the copied code by changing the path to the quick_jump.js file that has to point to the server location where you put the HTML file. For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code that you have to use:

          
 <script type="text/javascript">
   var BP_ontology_id = "FISHTRAITS";
 </div>
 <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>

        • to limit the term search to a particular branch of a semantic resource, include the following JavaScript in your page (remember to replace the conceptid with the ID for the term that you want to use as the root of your branch): var BP_search_branch = "{class_id}";

        • to display definitions with the list of terms that are returned, include the following JavaScript in your page: var BP_include_definitions = true;

      • Semantic resource visualization widget

        To add a widget visualizing your semantic resource in your HTML page, copy the code from the Widget page of your semantic resource of interest. Here is an example:

        <iframe src="http://ecoportal.lifewatchitaly.eu/widgets/visualization/?ontology=FISHTRAITS&class=SELECT_CLASS&apikey=YOUR_API_KEY"frameborder="0"> </iframe>

      • EcoPortal Semantic resource Tree Widget

        • Description

          The semantic resource tree widget is an embeddable Flex application that allows users to interact with a tree to browse semantic resources. The widget can be configured to display a list of all the EcoPortal semantic resources, allowing users to select which one to view, or can be set to view a particular semantic resource. Moreover, there are several JavaScript helper functions for the widget, allowing it to be used as a fully functional component in other applications.

        • Setup

          jQuery is required in order to use the tree widget. If jQuery is not still in your project, you have to include it as follows:

          <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

          Then, you have to create a div element to store the tree:

          <div id="tree"></div>

          initialize the tree with the following JavaScript code:

          var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "FISHTRAITS"});

          The div you created will contain a tree showing the roots of the FISHTRAITS semantic resource. Additional setup options include:

          • autoclose: to close other branches of the tree when expanding a new one;
          • treeClass: the class to identify the tree;
          • autocompleteClass: the class to identify the autocomplete (search) input;
          • width: the width of the tree;
          • startingClass: to start with this class selected (and expanded to) in the tree;
          • startingRoot: to start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing;
          • ncboAPIURL: to use a different NCBO REST instance (not normally used);
          • ncboUIURL: to use a different NCBO UI instance (not normally used).

        • Callbacks and Event Triggers

          You can interact programmatically with the tree by using JavaScript and jQuery. Callbacks can be passed when setting up the tree:

          var tree = $("#tree").NCBOTree({apikey: "YOUR_API_KEY",ontology: "FISHTRAITS", afterSelect: function(event, classId, prefLabel, selectedNode){console.log(classId);}});

          The available callbacks with their arguments are:

          • beforeExpand, arg: expandedNode
          • afterExpand, arg: expandedNode
          • afterExpandError, arg: expandedNode
          • afterSelect, arg: classId, prefLabel, selectedNode
          • afterJumpToClass, arg: classId

          You can also listen to these callbacks as jQuery events:

          tree.on("afterSelect", function(event, classId, prefLabel, selectedNode){console.log(classId);}

          The events with their arguments are:

          • beforeExpand, arg: event,expandedNode
          • afterExpand, arg: event,expandedNode
          • afterExpandError, arg: event,expandedNode
          • afterSelect, arg: event,classId, prefLabel, selectedNode
          • afterJumpToClass, arg: event,classId

        • Public Methods

          There are a variety of methods to call on the object that is returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

          var tree = $("#tree").data("NCBOTree");
          OR
          var tree = $("#tree")[0].NCBOTree;
          OR
          var tree = document.getElementById("tree").NCBOTree;

          Once you have the tree instance, you can call the following methods:

          • tree.selectedClass(): returns an object that represents the currently-selected class. The object includes attributes for ID, prefLabel, and URL. URL is the REST location of the class, and performing an HTTP GET on that URL will provide a JSON representation of the class;
          • tree.selectClass(classId): activates the class in the tree with the matching URI (classId). This will only work if the class is already visible;
          • tree.jumpToClass(classId): replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns;
          • tree.changeOntology(ontologyAcronym): replaces the current tree with the roots from the given semantic resource.

Copyright © 2021, LifeWatch ERIC. All rights reserved.

EcoPortal

Clone this wiki locally