Shortest Path Web Service

The Shortest Path Web service is used to get the shortest path between two UMBEL reference concepts by following the path of a transitive property. The concepts that belong to that path will be returned by the server.

This web service is similar to the distance web service endpoint but the actual path is known. This web service is (marginally) than distance. So if you don't need to know the actual concepts that participate to the shortest path between two concepts, then you should be using the distance web service endpoint instead.

The graph created by the UMBEL reference concepts ontology is a mostly an acyclic directed graph. This means that a given pair of concepts is not necessarely linked via all the properties.

Usage

This Web service is intended to be used by any user that wants to get the shortest path between two UMBEL reference concepts and know the concepts that participate to that path. 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.
 
HTTP Method:
  • GET
Possible Accept: HTTP header field value:
  • */*: return the distance in JSON
  • application/json: return the distance in JSON
  • application/*: return the distance in JSON
  • application/xml: return the distance in XML
  • text/xml: return the distance in XML
  • text/plain: return the distance in plain text
URL:
  • http://umbel.org/ws/shortest-path/uri-1/uri-2/property
Parameters:
  • uri-1: this parameter is the end URI of the starting UMBEL reference concept such as Person that refers to its full URI http://umbel.org/umbel/rc/Person.
  • uri-2: this parameter is the end URI of the ending UMBEL reference concept such as LegalAgent that refers to its full URI http://umbel.org/umbel/rc/LegalAgent.
  • property: this parameter is the transitive property to follow to find the shortest path between the two concepts. This parameter can be one of:
    • broader
    • narrower
    • sub-class-of
    • super-class-of

Serializations

The Get Concept endpoint currently supports three serialization formats:
  • JSON
  • XML
  • Plain text
 
The shortest path returned in JSON is a single object with a distance attribute and the actual distance as value.
 
  {
      "shortest-path": [
          {
              "uri": "http://umbel.org/umbel/rc/Person",
              "pref-label": "person"
          },
          {
              "uri": "http://umbel.org/umbel/rc/HomoSapiens",
              "pref-label": "human"
          },
          {
              "uri": "http://umbel.org/umbel/rc/HomoGenus",
              "pref-label": "genus Homo"
          },
          {
              "uri": "http://umbel.org/umbel/rc/Biped",
              "pref-label": "biped"
          }
      ]
  }
          
Note that if there is no path between two concepts, then the array of the shortest-path attribute will be empty.

Examples

Here are a series of examples that use cURL for querying the Shortest Path Web service endpoint.
 
Get the shortest path between the umbel:Person and the umbel:Biped reference concepts for the property broader in JSON:
  curl -H "Accept: application/json" "http://umbel.org/ws/distance/Person/Biped/broader"
 
Get the distance between the umbel:Person and the umbel:Biped reference concepts for the property broader in EDN:
  curl -H "Accept: application/edn" "http://umbel.org/ws/distance/Person/LegalAgent/broader"
 

Errors

Here is the list of possible HTTP errors that can be returned by this endpoint:
 
HTTP Error Message Description
404
Unknown reference concept URI: Concept The URI of one of the reference concepts does not exist.
404
Unknown property requested. It should be one of: broader, narrower, sub-class-of or super-class-of The specified property is not existing or has a typo.
404
The concept [uri-1] is not connected to the concept [uri-2] for this property [property] The two specified concepts are unconnected by the specified property.
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