Get Sub Classes Web Service

The Get Sub Classes Web service is used to get the list of all the sub classes of a given reference concept. This processing is done by inference, which means that if A -> B -> C are sub classes, then the sub classes of A are both B and C, which is what will be returned by the endpoint.

Usage

This Web service is intended to be used by any user that wants to get the sub classes of a given concept, by inference.
 
No permissions are required to query this web service endpoint. To access this endpoint, you simply have to send a HTTP GET query to the proper endpoint URL per the specifications below.
 
If you want additional contextual information about the target concept and its sub classes, then specify the ext parameter when creating the query. That way, you will get the preferred label and the distance of the returned sub classes. However, the extended parameter takes more time to compute. So if you do not need this information do not use the ext parameter.
 
HTTP Method:
  • GET
Possible Accept: HTTP header field value:
  • application/json: return the JSON serialization of the resultset
  • application/*: return the JSON serialization of the resultset
  • */*: return the JSON serialization of the resultset
  • application/clojure: return the Clojure serialization of the resultset
URL:
  • http://umbel.org/ws/sub-classes/[ext]/uri
Parameters:
  • ext: this is an optional path parameter. If it is set, then a extended resultset which includes the preferred label and the distance of the sub classes will be returned. A simple list of sub classes URIs will be returned if it is ommited.
  • uri: this parameter is the end URI of a UMBEL reference concept such as Person that refers to its full URI http://umbel.org/umbel/rc/Person.

Serializations

The Get Sub Classes endpoint currently supports two serialization formats:
  • JSON
  • Clojure code
 
The extended JSON resultset for the umbel:PlantProduct inferred sub classes looks like this:
 
The JSON structure of a extended Get Sub Classes resultset is an object composed of the URI of the sub classes as keys, and objects values composed of:
  • "pref-label" — the preferred label of the sub classe
  • "distance" — the distance between the target concept and the sub classe. The direct sub classe is at distance 1, then subsequent ones are of distance greater than 1.
 
  {
      "http://umbel.org/umbel/rc/PlantProduct": {
          "pref-label": "plant product",
          "distance": 0
      },
      "http://umbel.org/umbel/rc/Wicker": {
          "pref-label": "wicker",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/VegetableOil": {
          "pref-label": "vegetable oil",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Tobacco": {
          "pref-label": "tobacco",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Sucrose": {
          "pref-label": "sucrose",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Sawdust": {
          "pref-label": "sawdust",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Rubber_TheNaturalStuff": {
          "pref-label": "latex",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Puree": {
          "pref-label": "puree",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Opium": {
          "pref-label": "opium",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Nectar": {
          "pref-label": "nectar",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Loofah": {
          "pref-label": "loufah sponge",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Jute_Fiber": {
          "pref-label": "jute",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Hemp_Fiber": {
          "pref-label": "hemp fiber",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/GumArabic": {
          "pref-label": "gum acacia",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/GreenSalad": {
          "pref-label": "green salad",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/GrassTurf": {
          "pref-label": "grass",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Glucose": {
          "pref-label": "dextrose",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Fructose": {
          "pref-label": "levulose",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/FlourOrMeal": {
          "pref-label": "flour",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Flax_TheFiber": {
          "pref-label": "flax",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Coffee_Instant": {
          "pref-label": "instant coffee",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Coffee_Ground": {
          "pref-label": "ground coffee",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/BreakfastCereal": {
          "pref-label": "cereal",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/Arrowroot_Starch": {
          "pref-label": "arrowroot",
          "distance": 1
      },
      "http://www.w3.org/2004/02/skos/core#OrderedCollection": {
          "pref-label": null,
          "distance": 2
      },
      "http://www.w3.org/2004/02/skos/core#ConceptScheme": {
          "pref-label": null,
          "distance": 2
      },
      "http://www.w3.org/2004/02/skos/core#Collection": {
          "pref-label": null,
          "distance": 2
      },
      "http://umbel.org/umbel/rc/WheatFlour": {
          "pref-label": "wheat flour",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/SnuffTobacco": {
          "pref-label": "snuff tobacco",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/SesameOil": {
          "pref-label": "sesame oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/RiceFlour": {
          "pref-label": "rice flour",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/PeanutOil": {
          "pref-label": "peanut oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/PalmOil": {
          "pref-label": "palm oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/OliveOil": {
          "pref-label": "olive oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/LemonOil": {
          "pref-label": "lemon oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/HotCereal_Uncooked": {
          "pref-label": "hot cereal",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/HotCereal_Cooked": {
          "pref-label": "cooked cereal",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/CornMeal": {
          "pref-label": "corn meal",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/ColdCereal": {
          "pref-label": "cold cereal",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/CoconutOil": {
          "pref-label": "coconut oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/CastorOil": {
          "pref-label": "castor oil",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/CarrotPuree": {
          "pref-label": "carrot puree",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/CaesarSalad": {
          "pref-label": "Caesar salad",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/Muesli": {
          "pref-label": "muesli",
          "distance": 3
      },
      "http://umbel.org/umbel/rc/Granola": {
          "pref-label": "granola",
          "distance": 3
      }
  }          
          
 
 
The simple JSON resultset for the umbel:PlantProduct inferred sub classes looks like this. It is a simple JSON array of URIs:
 
  [
      "http://umbel.org/umbel/rc/PlantProduct",
      "http://umbel.org/umbel/rc/Opium",
      "http://umbel.org/umbel/rc/Arrowroot_Starch",
      "http://umbel.org/umbel/rc/Coffee_Instant",
      "http://umbel.org/umbel/rc/GreenSalad",
      "http://umbel.org/umbel/rc/VegetableOil",
      "http://umbel.org/umbel/rc/Puree",
      "http://umbel.org/umbel/rc/GrassTurf",
      "http://umbel.org/umbel/rc/GumArabic",
      "http://umbel.org/umbel/rc/Coffee_Ground",
      "http://umbel.org/umbel/rc/Flax_TheFiber",
      "http://umbel.org/umbel/rc/Nectar",
      "http://umbel.org/umbel/rc/Sawdust",
      "http://umbel.org/umbel/rc/Glucose",
      "http://umbel.org/umbel/rc/BreakfastCereal",
      "http://umbel.org/umbel/rc/Sucrose",
      "http://umbel.org/umbel/rc/Jute_Fiber",
      "http://umbel.org/umbel/rc/Loofah",
      "http://umbel.org/umbel/rc/Hemp_Fiber",
      "http://umbel.org/umbel/rc/Tobacco",
      "http://umbel.org/umbel/rc/Fructose",
      "http://umbel.org/umbel/rc/Wicker",
      "http://umbel.org/umbel/rc/FlourOrMeal",
      "http://umbel.org/umbel/rc/Rubber_TheNaturalStuff",
      "http://umbel.org/umbel/rc/SesameOil",
      "http://umbel.org/umbel/rc/RiceFlour",
      "http://umbel.org/umbel/rc/PalmOil",
      "http://umbel.org/umbel/rc/LemonOil",
      "http://www.w3.org/2004/02/skos/core#Collection",
      "http://umbel.org/umbel/rc/CornMeal",
      "http://umbel.org/umbel/rc/CoconutOil",
      "http://www.w3.org/2004/02/skos/core#OrderedCollection",
      "http://www.w3.org/2004/02/skos/core#ConceptScheme",
      "http://umbel.org/umbel/rc/WheatFlour",
      "http://umbel.org/umbel/rc/ColdCereal",
      "http://umbel.org/umbel/rc/OliveOil",
      "http://umbel.org/umbel/rc/CaesarSalad",
      "http://umbel.org/umbel/rc/PeanutOil",
      "http://umbel.org/umbel/rc/CarrotPuree",
      "http://umbel.org/umbel/rc/HotCereal_Uncooked",
      "http://umbel.org/umbel/rc/SnuffTobacco",
      "http://umbel.org/umbel/rc/HotCereal_Cooked",
      "http://umbel.org/umbel/rc/CastorOil",
      "http://umbel.org/umbel/rc/Muesli",
      "http://umbel.org/umbel/rc/Granola"
  ]
          
 

Examples

Here are a series of examples that use cURL for querying the get sub classes web service endpoint.
 
Get the simple list of the sub classes of the PlantProduct reference concept in JSON:
  curl -H "Accept: application/json" "http://umbel.org/ws/sub-classes/PlantProduct"
 
Get the extended list of the sub classes concepts of the PlantProduct reference concept in JSON:
  curl -H "Accept: application/json" "http://umbel.org/ws/sub-classes/ext/PlantProduct"
 
Get the simple list of the sub classes of the PlantProduct reference concept in Clojure:
  curl -H "Accept: application/clojure" "http://umbel.org/ws/sub-classes/PlantProduct"
 
Get the extended list of the sub classes of the PlantProduct reference concept in Clojure:
  curl -H "Accept: application/clojure" "http://umbel.org/ws/sub-classes/ext/PlantProduct"
 

Errors

Here is the list of possible HTTP errors that can be returned by this endpoint:
 
HTTP Error Message Description
404
Requested resource not existing The URL of the web service is not properly constructed. This usually happens if you write URLs like http://umbel.org/ws/sub-classes/PlantProduct/
406
Unsuppoted mime requested The Accept: HTTP headers doesn't contain any supported mime types. If this happens, make sure that you are requesting a supported mime type.
500
empty An internal UMBEL Web service error occurred. If this happens, please contact us with the query that caused the error.
 

Copyright © 2008-2017. Structured Dynamics LLC. All content available via Creative Commons Attribution 3.0