Get Super Classes Web Service

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

 
The super classes do include the super types as their top concept (use the Get Super-Class-Of web service endpoint for that).

Usage

This Web service is intended to be used by any user that wants to get the super class 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 super classes, then specify the ext parameter when creating the query. That way, you will get the preferred label and the distance of the returned super 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/super-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 super classes will be returned. A simple list of super 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 Super Classes endpoint currently supports two serialization formats:
  • JSON
  • Clojure code
 
The extended JSON resultset for the umbel:LegalAgent inferred super classes looks like this:
 
The JSON structure of a extended Get Super Classes resultset is an object composed of the URI of the super classes as keys, and objects values composed of:
  • "pref-label" — the preferred label of the super classe
  • "distance" — the distance between the target concept and the super classe. The direct super classe is at distance 1, then subsequent ones are of distance greater than 1.
 
  {
      "http://umbel.org/umbel/rc/LegalAgent": {
          "pref-label": "legal agent",
          "distance": 0
      },
      "http://umbel.org/umbel/rc/SocialBeing": {
          "pref-label": "social being",
          "distance": 1
      },
      "http://umbel.org/umbel/rc/IntelligentAgent": {
          "pref-label": "intelligent agent",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/Agent_PartiallyTangible": {
          "pref-label": "tangible agent",
          "distance": 2
      },
      "http://umbel.org/umbel/rc/InformationStore": {
          "pref-label": "store of information",
          "distance": 3
      },
      "http://umbel.org/umbel/rc/Agent_Generic": {
          "pref-label": "individual",
          "distance": 3
      },
      "http://umbel.org/umbel/rc/SomethingExisting": {
          "pref-label": "thing existing stably in time",
          "distance": 4
      },
      "http://umbel.org/umbel/rc/PartiallyIntangibleIndividual": {
          "pref-label": "partially intangible individual",
          "distance": 4
      },
      "http://umbel.org/umbel#TopicsCategories": {
          "pref-label": "topics categories",
          "distance": 4
      },
      "http://umbel.org/umbel/rc/PartiallyIntangible": {
          "pref-label": "partially intangible thing",
          "distance": 5
      },
      "http://umbel.org/umbel/rc/Individual": {
          "pref-label": null,
          "distance": 5
      },
      "http://umbel.org/umbel#SuperType": {
          "pref-label": "SuperType",
          "distance": 5
      },
      "http://umbel.org/umbel/rc/Thing": {
          "pref-label": "thing",
          "distance": 6
      },
      "http://umbel.org/umbel#AbstractLevel": {
          "pref-label": "abstract level",
          "distance": 7
      }
  }       
          
 
The simple JSON resultset for the umbel:PlantProduct inferred super classes looks like this. It is a simple JSON array of URIs:
 
  [
      "http://umbel.org/umbel/rc/LegalAgent",
      "http://umbel.org/umbel/rc/SocialBeing",
      "http://umbel.org/umbel/rc/IntelligentAgent",
      "http://umbel.org/umbel/rc/Agent_PartiallyTangible",
      "http://umbel.org/umbel/rc/InformationStore",
      "http://umbel.org/umbel/rc/Agent_Generic",
      "http://umbel.org/umbel/rc/PartiallyIntangibleIndividual",
      "http://umbel.org/umbel/rc/SomethingExisting",
      "http://umbel.org/umbel#TopicsCategories",
      "http://umbel.org/umbel/rc/PartiallyIntangible",
      "http://umbel.org/umbel#SuperType",
      "http://umbel.org/umbel/rc/Individual",
      "http://umbel.org/umbel/rc/Thing",
      "http://umbel.org/umbel#AbstractLevel"
  ]
          
 

Examples

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

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/super-classes/LegalAgent/
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